D3 · Claude Code › Cluster 2 · Settings & Configuration

2.2 · Key Settings You Must Know

model · env · permissions · hooks

CONCEPT The high-value keys in settings.json

Dozens of keys exist, but a handful come up constantly in real config and on the exam. Learn what each does and which type of value it takes:

KeyTypeWhat it does
modelstringDefault model for the session (e.g. "sonnet", "opus"); switch mid-session with /model
envobjectEnvironment variables injected into every session
permissionsobjectTool allow / deny / ask rules, defaultMode, additionalDirectories
hooksobjectShell commands run at lifecycle events (e.g. PreToolUse, PostToolUse)
apiKeyHelperstringCustom command that outputs the auth value / API key
includeCoAuthoredBybooleanAdd the Co-Authored-By: Claude trailer to git commits (default true)
cleanupPeriodDaysnumberDays to retain session transcripts (default 30)
statusLineobjectCustom status-line command shown in the footer
outputStylestringOutput rendering / response style
enableAllProjectMcpServersbooleanAuto-approve every MCP server declared in the project .mcp.json
forceLoginMethodstringRestrict auth to "claudeai", "console", or "gateway"
disableAllHooksbooleanTurn off all hooks and the custom status line
🔑 model, env, permissions, and hooks are the four you should be able to write from memory. The rest are recognition-level.

CONCEPT permissions — allow, deny, ask

The permissions object is where you shape autonomy. Rules are written as Tool(pattern), e.g. Bash(npm run test:*) or Read(./.env).

Sub-keyEffect
allowPatterns Claude may run without asking
denyPatterns Claude may never run (also blocks reads of secret files)
askPatterns that always prompt for confirmation first
defaultModeStarting permission mode for the session
additionalDirectoriesExtra directories outside the repo Claude may access
🚫 deny is the strongest rule: it beats allow. Use it to hard-block reads of ./.env, ./secrets/**, or dangerous commands like Bash(curl:*).

DIAGRAM Where each key takes effect

flowchart TD S["settings.json"] --> M["model → which model runs"] S --> E["env → vars for every session"] S --> P["permissions"] S --> H["hooks → run shell at lifecycle events"] P --> AL["allow: auto-run patterns"] P --> DE["deny: never-run (wins over allow)"] P --> AS["ask: confirm-first patterns"] H --> PRE["PreToolUse → validate/block a tool call"] H --> POST["PostToolUse → lint/format after a tool runs"] classDef key fill:#cfe2ff,stroke:#3d7bfe,color:#0a3a9a; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class M,E,P,H key; class AL,POST ok; class DE bad; class AS,PRE key;

CODE A realistic project settings.json

Model, injected env, permission rules, and a post-edit hook — the four heavy hitters in one file.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 20,

  "env": {
    "NODE_ENV": "development",
    "MAX_THINKING_TOKENS": "10000"
  },

  "permissions": {
    "allow": ["Bash(npm run test:*)", "Read(~/.zshrc)"],
    "deny":  ["Read(./.env)", "Read(./secrets/**)", "Bash(curl:*)"],
    "ask":   ["Bash(git push:*)"],
    "defaultMode": "acceptEdits"
  },

  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "npm run lint --silent" }]
    }]
  }
}
⚠️ Values in env are strings. A numeric-looking var like MAX_THINKING_TOKENS must still be quoted as "10000".

TRADE-OFFS Broad allow-list vs. tight deny-list

✅ Curated allow + explicit deny

  • Fewer confirmation prompts for known-safe commands
  • deny hard-blocks secrets and dangerous ops
  • Predictable, reviewable autonomy the team agrees on

⚠️ Wide-open allow (e.g. Bash(*))

  • Zero friction — but zero guardrails
  • One bad model call can run anything
  • Only a deny rule can claw a pattern back

EXAM TRAPS

Trap: "allow overrides deny if it's more specific." → No. deny always wins over allow. It's the safety backstop.
Trap: "Set the model with an ANTHROPIC_MODEL key inside settings.json." → The settings.json key is model. ANTHROPIC_MODEL is an environment variable, not a settings key (covered in 2.3).
Trap: "env takes numbers and booleans." → All env values are strings — quote them.
Trap: "includeCoAuthoredBy: false disables commits." → It only removes the Co-Authored-By: Claude trailer from commit messages; Claude can still commit.

PRACTICE

Q1 · A pattern is in both allow and deny. What happens?

It is denied. deny takes precedence over allow, so the command is blocked regardless of the allow rule.

Q2 · Which key runs a linter automatically after every file edit?

hooks, using a PostToolUse hook with a matcher like "Edit|Write" whose command runs the linter. PreToolUse runs before a tool and can block it; PostToolUse runs after.

Q3 · How do you stop transcripts from piling up for months?

Set cleanupPeriodDays to a smaller number (the default retention is 30 days). Claude Code deletes session files older than that window.