Settings Management

Settings Management

Manage configuration for coding agents.

IMPORTANT: After modifying settings, always inform the user that they need to restart the agent for changes to take effect. Most settings are only loaded at startup.

Settings File Locations

| Scope | Location | Shared with team? |

|-------|----------|-------------------|

| User | ~/.claude/settings.json | No |

| Project | .claude/settings.json | Yes (committed) |

| Local | .claude/settings.local.json | No (gitignored) |

| Managed | System-level managed-settings.json | IT-deployed |

Precedence (highest to lowest): Managed → Command line → Local → Project → User

Quick Actions

View Current Settings

cat ~/.claude/settings.json 2>/dev/null || echo "No user settings"
cat .claude/settings.json 2>/dev/null || echo "No project settings"
cat .claude/settings.local.json 2>/dev/null || echo "No local settings"

Create/Edit Settings

Use the Edit or Write tool to modify settings files. Always read existing content first to merge changes.

Common Configuration Tasks

Set Default Model

{
  "model": "claude-opus-4-7",
  "effort": "high"
}

Effort levels: low, medium, high, xhigh (Opus 4.7 only), max. As of 2026, default effort is high for API-key, Bedrock/Vertex/Foundry, Team, and Enterprise users.

Configure Permissions

{
  "permissions": {
    "allow": ["Bash(npm run:*)", "Bash(git:*)"],
    "deny": ["Read(.env)", "Read(.env.*)", "WebFetch"],
    "defaultMode": "acceptEdits"
  }
}

defaultMode accepts: default, acceptEdits, plan, auto, dontAsk, bypassPermissions. The new auto mode (March 2026) uses an LLM-based classifier and triggers PermissionDenied hooks on rejection.

Add Environment Variables

{
  "env": {
    "MY_VAR": "value",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

Enable Extended Thinking

{
  "alwaysThinkingEnabled": true
}

Configure Attribution

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "pr": ""
  }
}

Configure Sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"]
  }
}

Configure Hooks

{
  "hooks": {
    "PreToolUse": {
      "Bash": "echo 'Running command...'"
    }
  }
}

Scope Selection Guide

• User settings (~/.claude/settings.json): Personal preferences across all projects
• Project settings (.claude/settings.json): Team-shared settings, commit to git
• Local settings (.claude/settings.local.json): Personal project overrides, not committed

Workflow

• Determine scope: Ask user which scope (user/project/local) if not specified
• Read existing settings: Always read current file before modifying
• Merge changes: Preserve existing settings, only modify requested keys
• Validate JSON: Ensure valid JSON before writing
• Confirm changes: Show user the final settings
• Remind to restart: Tell user to restart Claude Code for changes to take effect

Codex CLI Settings

Codex uses TOML format in ~/.codex/config.toml (user) and .codex/config.toml (project, trusted projects only).

model = "gpt-5.5"                  # As of April 2026; gpt-5.4 is a valid fallback
approval_policy = "on-request"     # untrusted | on-request | never (or { granular = { ... } })
                                    # NOTE: "on-failure" is DEPRECATED — migrate to on-request or never
sandbox_mode = "workspace-write"   # read-only | workspace-write | danger-full-access

[features]
codex_hooks = true                 # Lifecycle hooks (stable in v0.124, April 2026)
multi_agent = true                 # Subagent orchestration (GA March 2026)

Key differences from Claude Code:

• TOML format instead of JSON; project config requires explicit trust
• Starlark rules for command policies in .codex/rules/
• Named profiles ([profiles.NAME]) for different workflows
• Feature flags system (codex features list, codex --enable feature)
• Lifecycle hooks live inline as [[hooks.PreToolUse]] (etc.) blocks in config.toml
• [agents] block for subagent orchestration (max_threads, max_depth)
• [[skills.config]] for per-skill enable/disable overrides
• Custom model providers via [model_providers.NAME], including amazon-bedrock since v0.123

See references/codex-settings.md for the full Codex config reference (covers approval/sandbox/profiles/features/agents/skills/hooks/rules/providers/admin enforcement).

OpenCode Settings

OpenCode (anomalyco/opencode v1.14.x) uses JSON/JSONC in ~/.config/opencode/opencode.json (user) and opencode.json (project root, or under .opencode/).

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "permission": {
    "edit": "ask",
    "bash": { "*": "ask", "git status *": "allow" }
  },
  "instructions": ["AGENTS.md", "docs/style.md"]
}

Key differences from Claude Code:

• Schema-validated JSON/JSONC, not plain JSON
• Configs are deep-merged (later wins; arrays like instructions are concatenated, not replaced)
• Permissions are an object of allow/ask/deny per tool with glob patterns, not separate allow/deny/ask arrays
• Theme/keybinds live in a separate tui.json file
• Multi-provider via model: "<provider>/<model-id>" and a top-level provider block
• Variable substitution: {env:VAR} and {file:path}

See references/opencode-settings.md for full OpenCode config reference.

Reference

• Claude Code settings: references/claude-settings.md
• Codex CLI settings: references/codex-settings.md
• OpenCode settings: references/opencode-settings.md