/settings-management

name: settings-management
description: View and configure settings for coding agents (Claude Code, Codex CLI, OpenCode, Devin CLI/Desktop, and others). Covers JSON settings for Claude Code and Devin, TOML for Codex CLI, and JSON/JSONC for OpenCode, including permissions, sandbox, model selection, profiles, feature flags, providers, hooks, subagents, and skills.

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 <ai@example.com>",
    "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

1. **Determine scope**: Ask user which scope (user/project/local) if not specified 2. **Read existing settings**: Always read current file before modifying 3. **Merge changes**: Preserve existing settings, only modify requested keys 4. **Validate JSON**: Ensure valid JSON before writing 5. **Confirm changes**: Show user the final settings 6. **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](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/opencod