Claude Code settings.json: Complete Configuration Reference (2026)

Claude Code reads configuration from two settings.json files:

• Global (~/.claude/settings.json): Applies to every project on your machine
• Project (.claude/settings.json): Project-specific overrides, checked into git

Project-level settings take precedence when a key appears in both.

File structure

{
  "permissions": {
    "allow": [],
    "deny": []
  },
  "env": {},
  "apiKeyHelper": "",
  "cleanupPeriodDays": 30,
  "includeCoAuthoredBy": true,
  "model": ""
}

permissions

Controls what Claude is allowed to do without asking for confirmation.

permissions.allow

A list of permission patterns that Claude can execute without a prompt.

{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint *)",
      "Bash(git log *)",
      "Bash(gh pr view *)",
      "mcp__filesystem__read_file",
      "mcp__github__get_file_contents"
    ]
  }
}

Pattern formats:

• Bash(exact-command) — allows this exact command
• Bash(prefix *) — allows any command starting with prefix (note the space before *)
• mcp__server-name__tool-name — allows a specific MCP tool

Examples that cover common workflows:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(pnpm run *)",
      "Bash(bun run *)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(git show *)",
      "Bash(git stash *)",
      "Bash(git branch *)",
      "Bash(gh pr *)",
      "Bash(gh issue *)",
      "Bash(gh run *)",
      "Bash(docker ps *)",
      "Bash(docker logs *)"
    ]
  }
}

Security note: Do not add Bash(python3 *), Bash(node *), or similar interpreter wildcards. These effectively allow arbitrary code execution.

permissions.deny

Explicitly blocks commands even if they'd otherwise be allowed.

{
  "permissions": {
    "deny": [
      "Bash(git push *)",
      "Bash(git push --force *)",
      "Bash(npm publish *)",
      "Bash(rm -rf *)"
    ]
  }
}

Deny rules take precedence over allow rules. Use this to create guardrails on destructive commands that should always require confirmation even in permissive projects.

env

Environment variables injected into every Claude Code session. Useful for setting API keys, feature flags, or project-specific config without polluting your shell profile.

{
  "env": {
    "ANTHROPIC_MODEL": "claude-3-5-haiku-20241022",
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug",
    "DATABASE_URL": "postgresql://localhost/myapp_dev"
  }
}

Important: These env vars are also passed to MCP servers launched by Claude Code. This is the right way to inject tokens into MCP servers without hardcoding them.

apiKeyHelper

A shell command that outputs your Anthropic API key. Use this instead of ANTHROPIC_API_KEY when you store keys in a secrets manager:

{
  "apiKeyHelper": "op read op://Personal/Anthropic/credential"
}

The command runs every time Claude Code starts. Works with 1Password CLI (op), AWS Secrets Manager, HashiCorp Vault, or any tool that can print a secret to stdout.

{
  "apiKeyHelper": "aws secretsmanager get-secret-value --secret-id anthropic-api-key --query SecretString --output text"
}

This is the correct pattern for teams that can't put API keys in environment variables.

cleanupPeriodDays

How long (in days) Claude Code retains local conversation history. Default is 30.

{
  "cleanupPeriodDays": 7
}

Set to a shorter period if disk space is a concern. Set to 0 to disable history entirely.

includeCoAuthoredBy

Whether to add Co-Authored-By: Claude to git commits made during the session. Default is true.

{
  "includeCoAuthoredBy": false
}

Useful if your git history tools flag the co-author line or if your team has a style guide that doesn't include AI attribution in commits.

model

Override the model used in this project. The model set here takes precedence over Claude Code's default.

{
  "model": "claude-3-5-haiku-20241022"
}

Use this in projects where you want a cheaper model by default (e.g., a project with frequent small queries), or to pin a specific model version for reproducibility.

Full example: team project configuration

A realistic .claude/settings.json for a TypeScript monorepo:

{
  "permissions": {
    "allow": [
      "Bash(pnpm run *)",
      "Bash(pnpm test *)",
      "Bash(pnpm lint *)",
      "Bash(pnpm typecheck *)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(git stash *)",
      "Bash(git branch *)",
      "Bash(gh pr *)",
      "Bash(gh issue *)",
      "Bash(docker ps)",
      "Bash(docker logs *)",
      "mcp__filesystem__read_file",
      "mcp__filesystem__list_directory",
      "mcp__github__get_file_contents",
      "mcp__github__list_issues",
      "mcp__postgres__query"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(pnpm publish *)",
      "Bash(docker rm *)",
      "Bash(docker rmi *)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost/myapp_dev",
    "REDIS_URL": "redis://localhost:6379"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30
}

Global defaults: ~/.claude/settings.json

Your global settings apply everywhere. A good baseline:

{
  "permissions": {
    "allow": [
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(git show *)",
      "Bash(git stash *)",
      "Bash(git branch *)",
      "Bash(gh pr *)",
      "Bash(gh issue *)",
      "Bash(gh run *)"
    ]
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30
}

Add project-specific permissions in .claude/settings.json instead of expanding the global file.

Local overrides: settings.local.json

For personal preferences you don't want to commit (personal API keys, personal workflow shortcuts), create .claude/settings.local.json in the project root and add it to .gitignore.

Same format as settings.json, applied after the project settings.

Verifying your configuration

From inside a Claude Code session:

/config    — shows active configuration
/permissions   — shows what's currently allowed and denied
/mcp   — shows connected MCP servers and their tools

Changes to settings.json take effect on the next session start — you don't need to reinstall anything.

For MCP server configuration (which lives in a separate file), see the Claude Code MCP setup guide.

For the full permissions model including granular control over tools and file access, see the Claude Code permissions guide.

Frequently Asked Questions

What is the difference between the global ~/.claude/settings.json and the project .claude/settings.json?

The global settings apply to every Claude Code session on your machine regardless of which project you are in. The project settings apply only when you are working inside that project directory. When the same key appears in both files, the project-level value takes precedence. Use global settings for personal defaults (git read commands, commit attribution) and project settings for repo-specific permissions.

Can I allow entire categories of bash commands with a wildcard in permissions.allow?

Yes, using the Bash(prefix *) pattern. For example, "Bash(npm run *)" allows all npm run subcommands without needing to list each one. The space before * is required. Be careful with broad wildcards like "Bash(python3 *)" — these effectively allow arbitrary code execution and should be avoided in shared configs.

How do I store my Anthropic API key securely without putting it in an environment variable?

Use the apiKeyHelper field with a command that retrieves the key from a secrets manager. For example, "apiKeyHelper": "op read op://Personal/Anthropic/credential" uses the 1Password CLI. The command runs at session startup, so the key is never stored in a file — it is fetched fresh each time from your secrets manager.

What is settings.local.json and when should I use it?

settings.local.json is a gitignored personal override file that layers on top of the project settings.json. Use it for developer-specific settings you don't want to commit: personal API keys, a different default model you prefer, or allow rules for commands specific to your local setup. Add .claude/settings.local.json to .gitignore so teammates' personal settings don't interfere.

Do changes to settings.json take effect immediately in a running session?

No. Settings are read at session startup. After editing any settings file, you must restart Claude Code for the changes to take effect. Run /config inside a session to see the currently active configuration and verify what settings are loaded.

Take It Further

Claude Code Power Prompts 300 — 300 battle-tested prompts for Claude Code, organized by use case. Copy, paste, ship.

40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.

→ Get Claude Code Power Prompts 300 — $29

30-day money-back guarantee. Instant download.