Originally published at claudeguide.io/claude-code-settings-json-reference

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

Claude Code reads configuration from two settings.json files: (2026)

• 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.

<div class="ai-disclosure"

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.