Claude Code settings.json: The Five-Layer Configuration Strategy
⚙️ Claude Code settings.json — The Complete Guide
📅 May 10, 2026 · Current as of Claude 4.x (Opus 4.7 / Sonnet 4.6 / Haiku 4.5)
config.json — it's settings.json. Merged across five layers (User, Project, Local, CLI, and Managed), it acts as a policy file that cleanly separates security from speed, and personal preferences from organizational mandates.
📌 1. The Bottom Line: The Correct Filename Is settings.json
Many guides and blog posts refer to Claude Code's global configuration file as ~/.claude/config.json, but this is incorrect. The Anthropic official documentation (Claude Code settings) designates three files as primary configuration channels:
▶ ~/.claude/settings.json — User-global settings
▶ <repo>/.claude/settings.json — Project-wide shared settings (commit to git)
▶ <repo>/.claude/settings.local.json — Personal local overrides (gitignore recommended)
config.json and .config.json are separate files that Claude Code uses internally to store state such as login tokens and usage cache. They are not a user-facing personalization channel meant for direct editing.
⚠️ Common Misconceptions
• Model IDs: claude-3-7-sonnet-latest and claude-3-5-sonnet-20241022 are both outdated. As of May 2026, the current generation is Claude 4.x (Opus 4.7 / Sonnet 4.6 / Haiku 4.5).
• CLAUDE.md is a context injection channel, not a configuration file. Its role is distinct from settings.json — do not conflate the two.
🏗️ 2. The Five-Layer Configuration Stack: Precedence Rules
Claude Code merges five layers in priority order. Layers listed lower in the table take precedence over those above.
| Priority | Layer | Path | Purpose |
|---|---|---|---|
| 1 (Lowest) | User | ~/.claude/settings.json |
Cross-project personal defaults |
| 2 | Project | <repo>/.claude/settings.json |
Shared team standard (committed to git) |
| 3 | Local | <repo>/.claude/settings.local.json |
Personal overrides (gitignored) |
| 4 | CLI Flags | claude --model … |
Per-session control |
| 5 (Highest) | Managed | /Library/Application Support/ClaudeCode/managed-settings.json |
Org IT/security policy enforcement |
📊 Layer Precedence — Visualized
The design intent is clear: "Shared standards belong in git, personal preferences stay local, and security policy lives at the org level." Even if a team's project settings auto-allow Bash(git push:*), an individual can lock that down further in settings.local.json — or, conversely, unlock experimental permissions that apply only to their own machine.
🔑 3. Key Configuration Categories
3.1 🤖 Model and Response Behavior
▶ model — Default model for the session. Accepts "claude-opus-4-7", "claude-sonnet-4-6", and so on.
▶ outputStyle — default / Explanatory / Learning.
▶ env — Environment variable map injected into the session. Use {"DEBUG": "1"} for tuning tool behavior.
3.2 🔐 Permissions and Security
Permissions follow a three-tier model: allow / ask / deny. Each tool-call pattern gets its own explicit policy.
"permissions": {
"allow": ["Read(**)", "Bash(git status:*)", "Bash(npm test:*)"],
"ask": ["Bash(git push:*)"],
"deny": ["Read(.env*)", "Bash(rm -rf:*)", "Bash(curl:*)"]
}
▶ additionalDirectories: Whitelist directories outside the workspace
▶ disableBypassPermissionsMode: Blocks the --dangerously-skip-permissions flag itself
3.3 🎨 UI and Interaction
▶ statusLine — Customizes the terminal status bar via a user script. Displays real-time token usage, Git branch, and cost estimates.
▶ theme — dark / light / dark-daltonized.
▶ cleanupPeriodDays — Auto-cleanup interval for inactive sessions and temp files (default: 30 days).
3.4 🔧 Automation and Authentication
▶ apiKeyHelper — Path to an external script that fetches the API key dynamically. The primary mechanism for integrating 1Password CLI or Keychain — keeps plaintext keys out of dotfiles entirely.
▶ awsAuthRefresh / awsCredentialExport — Automatic AWS Bedrock credential refresh.
▶ forceLoginMethod — Forces login channel: claudeai or console.
▶ includeCoAuthoredBy — Automatically appends Co-authored-by: Claude to git commit messages.
3.5 ⚡ Hooks: Enforcing Automated Behaviors (settings.json Only)
hooks, not in memory or CLAUDE.md. The model can forget or overlook instructions in memory; hooks are executed directly by the harness and fire unconditionally.
The hooks key wires event triggers to shell command execution. Supported events include:
▶ PreToolUse · PostToolUse — Before/after a tool call
▶ UserPromptSubmit — On user message submission
▶ SessionStart — On session start (for context injection)
▶ Stop — On response completion
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [{ "type": "command",
"command": "npm run lint --silent || true" }] }
]
}
3.6 🔌 MCP, Sub-agents, and Skills
▶ mcpServers — Connects external tools such as GitHub, Notion, and Playwright. (Typically stored in a separate .mcp.json or ~/.claude.json; settings.json controls enable/disable.)
▶ enabledPlugins / enabledSkills — Toggle activation of org-deployed plugins and skills.
🚀 4. Five Ways settings.json Pays Off
📐 Execution Flow: Minimizing Friction vs. Enforcing Safety
🟢 4.1 Reducing Friction
Register safe commands like Read, git status, and npm test in allow, and the per-call confirmation prompt disappears. Conversely, lock git push, rm, and curl under ask/deny to block accidents — a clean separation between speed and safety becomes possible.
💰 4.2 Cost and Performance Tuning
Large-scale refactors call for Opus 4.7; routine documentation edits can drop down to Haiku 4.5. Switch instantly with the model key or a CLI flag. Attach a token counter to statusLine and cost becomes visible — reducing wasteful, open-ended calls.
🔑 4.3 Credential Hygiene
Point apiKeyHelper at a 1Password or Keychain script to retrieve the API key at runtime, and the key never lands in your dotfiles. In a multi-device setup, the cost of key rotation approaches zero.
👥 4.4 Team Standardization
Commit .claude/settings.json to git and every team member instantly inherits the same permission policies, hooks, and outputStyle. Enforcing "no commit before tests pass" via a PostToolUse hook means broken code cannot be committed, even by accident.
⚙️ 4.5 The Real Entry Point for Workflow Automation
Requests like "from now on, always do this" are fragile when stored in memory. Define them in hooks and they fire unconditionally, without any hand-off. This goes beyond simple personalization — it codifies your workflow as enforced policy.
⚠️ 5. Security Risks and Anti-Patterns
| Risk Pattern | Why It's Dangerous / How to Prevent It |
|---|---|
| ❌ Overly Broad allow | Bash(*) and Read(**) expose the full attack surface to prompt injection. A malicious external README that says "run this command" will pass unchallenged. |
| ❌ Helper Script Privilege Leak | If the script pointed to by apiKeyHelper is world-writable, anyone can modify it and execute arbitrary code in every Claude session. chmod 700 is mandatory. |
| ❌ Missing deny for Sensitive Files | Omitting .env, id_rsa, and credentials/ from deny leaves them exposed — anyone could accidentally pull them into Claude's context. |
| ❌ No Managed Layer | Without disableBypassPermissionsMode: true in the Managed layer, users can disable every safety guard with --dangerously-skip-permissions. Enterprise deployments must lock this down. |
🚦 Decision Tree: Before Adding a New Permission Pattern
📋 6. Recommended Workflow: Personal → Project → Org
1. Personal Baseline — Set model, outputStyle, theme, apiKeyHelper, allow patterns for safe tools, and cleanupPeriodDays in ~/.claude/settings.json.
2. Project Standard — Define repo-specific permission policies and lint/test hooks in <repo>/.claude/settings.json and commit it to git.
3. Personal Override — Add <repo>/.claude/settings.local.json to .gitignore and use it for machine-specific permissions or debug-only environment variables.
4. Org Policy — The security team seals disableBypassPermissionsMode, permissions.deny, and the enabledPlugins whitelist via managed-settings.json.
5. Validation — Confirm the merged result with claude config list or the /config UI; trace hook behavior with claude --debug.
🧠 7. Key Takeaways
💡 One-Liner
settings.json is not a simple options file — it is a policy file that codifies the rules you would otherwise repeat on every session. The five-layer structure separates responsibility across individuals, teams, and organizations, while keys like hooks, permissions, and apiKeyHelper make safe automation possible.
📝 Three Things to Remember
▶ The filename is settings.json. config.json is not intended for user edits.
▶ Always verify that your model ID points to a current Claude 4.x variant. A stale ID may silently downgrade the model in use.
▶ "Always do X" belongs in hooks, not memory. Memory can be forgotten; hooks are enforced.
📚 References
▶ Anthropic Docs — Claude Code settings
▶ Anthropic Docs — Claude Code hooks
This guide reflects documentation current as of May 2026. Given Claude Code's rapid update cadence, cross-check with the official docs before applying any configuration.
A curated collection of software development resources — gathered, organized, and verified before publishing.
Written based on publicly available data and sources. Last updated: June 8, 2026
댓글
댓글 쓰기