DEV Community

Sangmin Lee
Sangmin Lee

Posted on • Originally published at claudeguide.io

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

#settings #configuration #reference

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": ""
}
Enter fullscreen mode Exit fullscreen mode

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"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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 *)"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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 *)"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)