Anatomy of .claude/settings.json

Every key, matcher, permission, and gotcha explained.

.claude/settings.json

The control tower for Claude Code — every key, every matcher, every gotcha.

TL;DR

.claude/settings.json is the single JSON file that controls Claude's behavior in a workspace.
It governs permissions, hooks, env vars, MCP servers, model choice, telemetry, UI — and more.
Three locations stack with precedence: Local > Workspace > Global > Defaults.
Commit settings.json; never commit settings.local.json (personal/secret overrides).
Treat it like production code: review, version, test before deploying.

Why this matters

Think of settings.json as the circuit breaker panel for your AI teammate. Flip the right switches and you get a safe, predictable collaborator. Flip the wrong ones (or none) and you've handed it the master key to your repo.

Bottom line: This one file decides what Claude can, can't, and must do.

File Location & Precedence

Scope	Path	Committed?	Purpose
Defaults	Built-in	n/a	Sensible factory defaults
Global	`~/.claude/settings.json`	No	Your personal cross-project defaults
Workspace	`.claude/settings.json`	✅ Yes	Team-shared rules
Local	`.claude/settings.local.json`	❌ No (`.gitignore` it)	Per-developer overrides, secrets

Bottom line: Lower in the table = higher precedence.

Top-Level Keys (the full map)

Key	Purpose	Required	Default
`version`	Config version	No	`"1.0"`
`model`	Model selection & fallback behavior	No	Workspace default
`permissions`	Sandbox allow/deny rules	No	Strict deny
`hooks`	Lifecycle event automation	No	None
`mcpServers`	External tool connections	No	None
`env`	Environment variables	No	`{}`
`features`	Feature flags	No	Built-in defaults
`telemetry`	Analytics & usage opt-in	No	Enabled
`ui`	UI & display preferences	No	Built-in defaults
`logging`	Logging configuration	No	`info`
`security`	Security & compliance	No	Safe defaults

1. `version`

{ "version": "1.0" }

⚠️ Gotcha: A missing version is silently treated as "1.0". Set it explicitly so future schema changes don't bite you.

2. `model` — selection & fallback chain

"model": {
  "default": "claude-opus-4",
  "fallback": ["claude-sonnet-4", "claude-haiku-4"],
  "temperature": 0.2,
  "max_tokens": 8000
}

Field	Purpose
`default`	Primary model
`fallback`	Ordered list tried on error/budget cap
`temperature`	0.0–1.0; lower = more deterministic
`max_tokens`	Output cap per turn

💡 Tip: Set temperature: 0.2 for code; 0.7 for ideation.

3. `permissions` — sandbox rules ⭐ the big one

"permissions": {
  "allow": [
    "Read",
    "Edit",
    "Bash(npm run *)",
    "Bash(git *)"
  ],
  "deny": [
    "WriteOutsideWorkspace",
    "Bash(rm -rf *)",
    "Bash(sudo *)"
  ],
  "ask": [
    "Bash(curl *)",
    "WebSearch"
  ]
}

How matching works

Rules are matched in order, first match wins.
deny overrides allow only if it appears earlier or is more specific.
Wildcards use glob-style patterns, not full regex.
Unmatched actions fall through to a default deny.

Permission categories

Category	Examples
File ops	`Read`, `Write`, `Edit`, `WriteOutsideWorkspace`
Shell	`Bash`, `Bash(npm )`, `Bash(git )`
Network	`WebSearch`, `WebFetch`, `WebFetch(domain:github.com)`
MCP tools	`MCP:`, `MCP:github`, `MCP:postgres(SELECT )`
Built-in tools	`Grep`, `Glob`, `Task`, `TodoWrite`

Common gotchas ⚠️

Bash(sudo *) in allow = privilege escalation. Never.
Bash(*) is way too broad — prefer Bash(npm run *).
WriteOutsideWorkspace blocks edits outside the repo root — keep it in deny.
Specific patterns override wildcards: list Bash(rm -rf *) in deny before any Bash(*) in allow.
ask prompts the user — great for "risky but sometimes needed" actions like curl.

4. `hooks` — lifecycle automation

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        { "type": "command", "command": "./scripts/pre-tool.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        { "type": "command", "command": "npm run lint" },
        { "type": "command", "command": "npm test" }
      ]
    }
  ],
  "PreCommit": [
    {
      "matcher": "*",
      "hooks": [
        { "type": "command", "command": "./scripts/secret-scan.sh" }
      ]
    }
  ],
  "Notification": [
    {
      "matcher": "*",
      "hooks": [
        { "type": "webhook", "url": "https://hooks.slack.com/...", "timeoutMs": 5000 }
      ]
    }
  ]
}

Hook events

Event	Fires when	Typical uses
`PreToolUse`	Before any tool call	Block unsafe commands, secret scan, policy checks
`PostToolUse`	After a tool call	Lint, tests, format, notify
`PreCommit`	Before git commit	Secret scan, policy, licence check
`Notification`	Important events	Slack/webhook, audit
`SessionStart`	Session opens	Load context, env summary
`SessionEnd`	Session closes	Save summary, audit
`Error`	Hook or tool error	Alert, rollback, capture logs

Hook entry format

{
  "matcher": "<regex>",            // when this hook runs
  "hooks": [
    { "type": "command",  "command": "./scripts/x.sh" },
    { "type": "webhook",  "url": "https://...",  "timeoutMs": 5000 },
    { "type": "script",   "script": "./scripts/policy.js", "env": { "FOO": "bar" } },
    { "type": "builtin",  "action": "lint" },
    { "type": "custom",   "name": "my-integration", "config": { } }
  ],
  "concurrency": "sequential"      // or "parallel"
}

Hook type cheat sheet

Type	What it does
`command`	Runs a shell command
`script`	Runs a script file (Node/Python/Bash)
`webhook`	Sends an HTTP request
`builtin`	Calls an internal Claude action
`custom`	Hooks a registered custom integration

Matcher language — what can they actually match?

Matchers are regex-like patterns matched against the tool name (and sometimes args).

Matcher	Matches	Example
`*`	Everything	All tools & all actions
`Read`	Read operations	Read file, list dir, search
`Write`	Write operations	Create file, overwrite
`Edit`	Edits to existing files	Patch, replace, apply diff
`Write\|Edit`	OR pattern	Either Write or Edit
`Bash`	All Bash commands	Includes sub-matchers
`Bash(npm *)`	Shell with arg pattern	`npm test`, `npm install`
`Bash(git *)`	Git commands	`git status`, `git commit`
`Bash(rm -rf *)`	Dangerous deletion	`rm -rf /tmp/*`
`WebSearch` / `WebFetch`	Network ops	`WebSearch(...)`
`MCP:*`	Any MCP tool	All MCP calls
`MCP:github`	Only GitHub MCP	Issues, PR actions
`Tool:fs`	Filesystem tools	`fs:read`, `fs:write`
`Tool:browser`	Browser automation	`browser:navigate`, click

Hook gotchas ⚠️

Hooks block the agent until they finish — keep them under 5 s.
A PreToolUse hook that exits non-zero blocks the tool call (use exit 1 to deny).
Hooks are NOT sandboxed — they run with your user's permissions. Audit script contents.
webhook hooks should have short timeoutMs (1–5 s) — avoid hanging the session.
concurrency: "parallel" is faster but unsafe if hooks share state.
Matchers are case-sensitive.
A * matcher fires on every event — use sparingly.

5. `mcpServers` — external tool connections

"mcpServers": {
  "github": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-github"],
    "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
  },
  "postgres": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-postgres"],
    "env": { "DATABASE_URL": "${DATABASE_URL}" }
  }
}

⚠️ Gotcha: You can define MCP servers here, but a dedicated .mcp.json is preferred for cleanliness. If both exist, .mcp.json typically wins — verify with claude mcp list.

Other gotchas

Never hard-code tokens — always ${ENV_VAR} interpolation.
The server name is the alias Claude uses (@github).
A failed server start = the tool silently becomes unavailable. Check claude mcp status.

6. `env` — environment variables

"env": {
  "MAX_THINKING_TOKENS": "100000",
  "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
  "NO_COLOR": "1",
  "NODE_OPTIONS": "--max-old-space-size=4096"
}

Common variables

Variable	Purpose	Example
`MAX_THINKING_TOKENS`	Cap reasoning tokens per turn	`"100000"`
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	Auto-compact context at % usage	`"50"`
`NO_COLOR`	Disable ANSI colors	`"1"`
`CLAUDE_CODE_TELEMETRY_DISABLED`	Disable telemetry	`"1"`
`NODE_OPTIONS`	Node runtime options	`"--max-old-space-size=4096"`

⚠️ Gotcha: Values must be strings — "50", not 50. Numbers will silently coerce or be rejected.

7. `features` — feature flags

"features": {
  "strictComplexity": true,
  "skipPermissionsConfirm": false,
  "codebaseIndexing": true,
  "fastApply": true,
  "enableTelemetry": false,
  "autoCompact": true,
  "codebaseSearch": true,
  "showToolUseNotifications": true,
  "allowedDomains": ["github.com", "docs.anthropic.com"]
}

Flag	What it does
`autoCompact`	Auto-manage context size
`skipPermissionsConfirm`	Skip confirm prompts (dangerous)
`codebaseIndexing`	Index codebase for search
`fastApply`	Apply patches faster
`allowedDomains`	Restrict web fetch to a list

⚠️ Gotcha: skipPermissionsConfirm: true removes the human safety net. Only use in CI or isolated containers.

8. `telemetry`

"telemetry": {
  "enabled": false,
  "level": "minimal",
  "endpoint": null
}

Set enabled: false for regulated environments.

9. `ui` — display preferences

"ui": {
  "theme": "auto",          // auto | light | dark
  "diffMode": "unified",    // unified | split | side-by-side
  "showToolUseNotifications": true,
  "expandThoughts": false
}

10. `logging`

"logging": {
  "level": "info",                       // trace | debug | info | warn | error
  "file": ".claude/logs/claude-code.log",
  "maxSizeMB": 20,
  "maxFiles": 5
}

⚠️ Gotchas:

Logs may contain file paths and command args — review before sharing.

Rotate logs to avoid disk bloat.

Never log secrets — scrub env values in custom hooks.

11. `security`

"security": {
  "secretScan": true,
  "blockSecretCommit": true,
  "scanPatterns": ["api[_-]?key", "secret", "token"],
  "auditLog": ".claude/logs/audit.log"
}

Complete Annotated Example

{
  "version": "1.0",
  "name": "My App Workspace",

  // ── Model selection & fallback chain ──
  "model": {
    "default": "claude-opus-4",
    "fallback": ["claude-sonnet-4", "claude-haiku-4"],
    "temperature": 0.2
  },

  // ── Sandbox permissions ──
  "permissions": {
    "allow": ["Read", "Edit", "Bash(npm run *)", "Bash(git *)"],
    "deny":  ["WriteOutsideWorkspace", "Bash(rm -rf *)", "Bash(sudo *)"],
    "ask":   ["Bash(curl *)", "WebSearch"]
  },

  // ── Lifecycle hooks ──
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "./scripts/pre-tool.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "npm run lint" },
          { "type": "command", "command": "npm test" }
        ] }
    ],
    "PreCommit": [
      { "matcher": "*",
        "hooks": [{ "type": "command", "command": "./scripts/secret-scan.sh" }] }
    ],
    "SessionEnd": [
      { "matcher": "*",
        "hooks": [{ "type": "command", "command": "./scripts/session-end.sh" }] }
    ]
  },

  // ── MCP servers ──
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  },

  // ── Environment variables ──
  "env": {
    "MAX_THINKING_TOKENS": "100000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "NO_COLOR": "1"
  },

  // ── Feature flags ──
  "features": {
    "autoCompact": true,
    "codebaseIndexing": true,
    "fastApply": true,
    "allowedDomains": ["github.com", "docs.anthropic.com"]
  },

  // ── Telemetry ──
  "telemetry": { "enabled": false },

  // ── UI ──
  "ui": { "theme": "auto", "diffMode": "unified" },

  // ── Logging ──
  "logging": {
    "level": "info",
    "file": ".claude/logs/claude-code.log",
    "maxSizeMB": 20,
    "maxFiles": 5
  },

  // ── Security ──
  "security": {
    "secretScan": true,
    "blockSecretCommit": true,
    "auditLog": ".claude/logs/audit.log"
  }
}

Variants for Different Team Settings

👤 Solo developer (permissive but safe)

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash(npm *)", "Bash(git *)", "WebSearch"],
    "deny":  ["WriteOutsideWorkspace", "Bash(rm -rf *)", "Bash(sudo *)"]
  },
  "hooks": {
    "PostToolUse": [
      { "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npm run lint -- --fix" }] }
    ]
  }
}

👥 Small team (shared standards)

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash(npm run *)", "Bash(git *)"],
    "deny":  ["WriteOutsideWorkspace", "Bash(rm -rf *)", "Bash(sudo *)"],
    "ask":   ["WebSearch"]
  },
  "hooks": {
    "PreToolUse":  [{ "matcher": "*",          "hooks": [{ "type": "command", "command": "./scripts/policy.sh" }] }],
    "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npm run lint" }] }],
    "PreCommit":   [{ "matcher": "*",          "hooks": [{ "type": "command", "command": "./scripts/secret-scan.sh" }] }]
  }
}

🏢 Enterprise / regulated (fail closed)

{
  "permissions": {
    "allow": ["Read", "Bash(npm test)"],
    "deny":  ["Write", "Edit", "WriteOutsideWorkspace",
              "Bash(curl *)", "Bash(sudo *)", "WebSearch", "WebFetch"]
  },
  "features": { "skipPermissionsConfirm": false, "enableTelemetry": false },
  "telemetry": { "enabled": false },
  "hooks": {
    "PreToolUse": [
      { "matcher": "*",
        "hooks": [
          { "type": "command", "command": "./scripts/policy-check.sh" },
          { "type": "webhook", "url": "https://siem.corp/audit", "timeoutMs": 3000 }
        ] }
    ],
    "SessionEnd": [
      { "matcher": "*",
        "hooks": [{ "type": "command", "command": "./scripts/audit-flush.sh" }] }
    ]
  },
  "security": { "secretScan": true, "blockSecretCommit": true, "auditLog": "/var/log/claude/audit.log" }
}

🌍 Open-source (welcoming + safe)

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash(npm test)", "WebSearch"],
    "deny":  ["WriteOutsideWorkspace", "Bash(rm -rf *)"]
  },
  "features": { "allowedDomains": ["github.com", "docs.anthropic.com", "npmjs.com"] }
}

Bottom line: Start permissive solo, tighten as team & risk grow.

Common Patterns & Recipes

Pattern 1 — Auto-lint after writes

"PostToolUse": [{ "matcher": "Write|Edit",
  "hooks": [{ "type": "command", "command": "npx prettier --write ." }] }]

Pattern 2 — Block dangerous deletes (specific before broad)

"permissions": {
  "deny":  ["Bash(rm -rf /*)", "Bash(rm -rf *)"],
  "allow": ["Bash(rm *)"]
}

Pattern 3 — Domain allowlist for web

"features": { "allowedDomains": ["github.com", "docs.anthropic.com"] }

Pattern 4 — Per-developer overrides (`settings.local.json`)

{
  "model": { "default": "claude-haiku-4" },
  "ui":    { "theme": "dark" }
}

Pattern 5 — Slack on every session end

"SessionEnd": [{ "matcher": "*",
  "hooks": [{ "type": "webhook", "url": "https://hooks.slack.com/...", "timeoutMs": 3000 }] }]

Best Practices ✅

Commit settings.json; gitignore settings.local.json.
Start strict (deny: ["*"] + explicit allow), then loosen with intent.
List specific deny rules before broad allow rules.
Keep hooks under 5 s — they block the agent.
Use ${ENV_VAR} for all secrets.
Review changes in PR like production code.
Test in settings.local.json before promoting to workspace.

Anti-Patterns ❌

Bash(*) in allow — too broad.
Hard-coded tokens / secrets in the file.
skipPermissionsConfirm: true outside of CI.
Hooks that block for > 10 s.
Editing settings.json directly without team review.
Mixing personal preferences (theme, model) with team rules.

Troubleshooting

Symptom	Likely cause	Fix
Tool unexpectedly denied	Deny pattern too broad	Inspect with `claude config explain`
Hook doesn't fire	Matcher regex mismatch	Test with `matcher: "*"` first
`${VAR}` not interpolated	Var not exported	`export VAR=...` then restart
Slow agent	Hooks too long	Profile + move to async
Settings ignored	Wrong file path/scope	Confirm precedence (Local > Workspace > Global)
Webhook hangs session	Missing `timeoutMs`	Set `timeoutMs: 3000`
MCP tool missing	Server failed to start	`claude mcp status` to debug

Minimal Starter Template (copy-paste)

{
  "version": "1.0",
  "permissions": {
    "allow": ["Read", "Edit", "Bash(npm run *)"],
    "deny":  ["WriteOutsideWorkspace", "Bash(rm -rf *)"]
  },
  "hooks": {
    "PreToolUse":  [{ "matcher": "*",          "hooks": [{ "type": "command", "command": "./scripts/pre-tool.sh" }] }],
    "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npm run lint" }] }]
  }
}

💡 Tip: This file is powerful — treat it like production code.

Glossary

Allow / Deny / Ask — Permission verdicts: green, red, prompt-user.
Matcher — A glob/regex-like pattern that scopes a hook or permission.
Precedence — The order in which configs override each other.
Sandbox — The set of allowed operations Claude may perform.
Hook — Shell/webhook command bound to a lifecycle event.
Interpolation — ${VAR} substitution from the process environment.
Fail closed — Block on error (safe). Fail open — Continue on error (convenient).

TL;DR​

Why this matters​

File Location & Precedence​

Top-Level Keys (the full map)​

1. version​

2. model — selection & fallback chain​

3. permissions — sandbox rules ⭐ the big one​

How matching works​

Permission categories​

Common gotchas ⚠️​

4. hooks — lifecycle automation​

Hook events​

Hook entry format​

Hook type cheat sheet​

Matcher language — what can they actually match?​

Hook gotchas ⚠️​

5. mcpServers — external tool connections​

6. env — environment variables​

Common variables​

7. features — feature flags​

8. telemetry​

9. ui — display preferences​

10. logging​

11. security​

Complete Annotated Example​

Variants for Different Team Settings​

👤 Solo developer (permissive but safe)​

👥 Small team (shared standards)​

🏢 Enterprise / regulated (fail closed)​

🌍 Open-source (welcoming + safe)​

Common Patterns & Recipes​

Pattern 1 — Auto-lint after writes​

Pattern 2 — Block dangerous deletes (specific before broad)​

Pattern 3 — Domain allowlist for web​

Pattern 4 — Per-developer overrides (settings.local.json)​

Pattern 5 — Slack on every session end​

Best Practices ✅​

Anti-Patterns ❌​

Troubleshooting​

Minimal Starter Template (copy-paste)​

Glossary​

Further Reading​