Claude Code Settings and Permissions#

Settings file locations#

Claude Code loads settings from multiple locations and merges them. More specific files override broader ones.

Precedence (highest to lowest): settings.local.json → project settings.json → user settings.json.

Full schema#

{
  "model": "claude-opus-4-7",
  "permissions": {
    "allow": [],
    "deny": []
  },
  "env": {},
  "apiKeyHelper": "",
  "cleanupPeriodDays": 30
}

model#

Set the default model for all sessions. Can be overridden per-session with /model.

{
  "model": "claude-sonnet-4-6"
}

Valid values: "claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5-20251001".

permissions#

Control which tools Claude can use without prompting. Rules in allow are auto-approved; rules in deny are auto-rejected.

Permission rule syntax#

"ToolName"                    // exact tool name — all uses
"ToolName(subcommand)"        // specific subcommand or pattern
"Bash(git *)"                 // glob: any git subcommand
"Bash(npm run *:npm test)"    // colon-delimited list of patterns

Allow rules#

Pre-approve specific tools so Claude never prompts for them:

{
  "permissions": {
    "allow": [
      "Read",
      "Bash(git log:git diff:git status:git blame)",
      "Bash(npm test:npm run lint:npm run build)",
      "Bash(python -m pytest:ruff check:ruff format)"
    ]
  }
}

Deny rules#

Always block specific tools regardless of what Claude requests:

{
  "permissions": {
    "deny": [
      "Bash(rm *:rmdir *)",
      "Bash(git push *:git force-push *)",
      "WebSearch",
      "WebFetch"
    ]
  }
}

Available tool names#

[!TIP] For CI/CD use --dangerously-skip-permissions to bypass all prompts. Only safe in isolated environments — never interactive use.

Read-only project example#

Useful for code review or analysis tasks where you don’t want Claude writing files:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "Bash(git log:git diff:git status:git show)"
    ],
    "deny": [
      "Edit",
      "Write",
      "MultiEdit",
      "Bash"
    ]
  }
}

Safe CI example#

Allow tests and linting but block file writes and network:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test:npm run lint:python -m pytest:ruff check)"
    ],
    "deny": [
      "Write",
      "Edit",
      "WebSearch",
      "WebFetch",
      "Bash(git push *)"
    ]
  }
}

env#

Inject environment variables into every Claude Code session. Useful for pointing to dev tools, setting API keys, or configuring language runtimes.

{
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost/myapp_dev",
    "PYTHONPATH": "/Users/jay/Code/myproject/src"
  }
}

[!WARNING] Don’t put ANTHROPIC_API_KEY in a committed settings file. Use settings.local.json or your shell profile instead.

apiKeyHelper#

A shell command that outputs your API key. Useful when the key is in a secrets manager rather than an environment variable.

{
  "apiKeyHelper": "op read op://dev/anthropic/api_key"
}

The command is run once at startup; its stdout becomes the API key.

cleanupPeriodDays#

How many days of session history to retain before automatic cleanup. Default is 30.

{
  "cleanupPeriodDays": 90
}

Complete example: team project settings#

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "Bash(git log:git diff:git status:git blame:git stash)",
      "Bash(npm install:npm test:npm run lint:npm run build)",
      "Bash(python -m pytest:ruff check:ruff format:mypy)"
    ],
    "deny": [
      "Bash(git push *:git push --force *)",
      "Bash(rm -rf *)",
      "WebFetch"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "cleanupPeriodDays": 60
}

Complete example: personal global settings#

{
  "model": "claude-opus-4-7",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "Bash(git log:git diff:git status)",
      "WebSearch"
    ],
    "deny": []
  },
  "cleanupPeriodDays": 30
}

Environment variables (shell-level)#

These variables affect Claude Code behavior when set in your shell before launching:

Check effective settings#

# Open settings in your editor
claude /config

# Or view the file directly
cat ~/.claude/settings.json
cat .claude/settings.json