Advanced

Settings & Permissions

Claude Code's settings.json controls what tools are pre-approved, what permission mode is active, how the API key is sourced, and what directories Claude Code can access. Understanding and configuring these settings is essential for a productive and safe workflow.

settings.json Structure

Claude Code uses two settings files:

Global: ~/.claude/settings.json — applies to all projects
Project-level: .claude/settings.json in the project root — applies only in this project, overrides global where they conflict

{
  "model": "claude-opus-4-6",
  "allowedTools": ["Bash(npm run test)", "Bash(npm run build)", "Edit", "Write"],
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm *)"],
    "deny": ["Bash(rm -rf *)", "Bash(git push --force *)"]
  },
  "mcpServers": { ... },
  "hooks": { ... }
}

allowedTools: Pre-Approving Without Prompts

The allowedTools array lists tool patterns that Claude Code is allowed to use without prompting you each time. Patterns use glob-style matching:

"Edit" — approve all file edits without prompting
"Write" — approve all file writes without prompting
"Bash(npm *)" — approve any shell command starting with npm
"Bash(git log *)" — approve git log commands but not git push or git reset
"Bash(npm run test)" — approve only this exact command

Building up your allowedTools by approving common patterns during normal sessions (using "Allow always" at prompts) is the recommended approach — it creates a permission set that matches your actual workflow.

Explicit Allow and Deny Rules

The permissions block lets you define explicit allow and deny rules that override the default prompt behaviour:

allow: Patterns that are always permitted — equivalent to allowedTools but supports more complex patterns
deny: Patterns that are always blocked — Claude Code will refuse these commands even if it would otherwise attempt them. This is a safety net for dangerous operations.

Deny rules take precedence over allow rules. A command matching both an allow and a deny pattern will be blocked.

API Key Management

Claude Code sources the API key in this priority order:

Environment variable ANTHROPIC_API_KEY — set in your shell profile or passed at runtime
Claude.ai OAuth session — authenticated via claude login
API key in settings.json (not recommended — avoid hardcoding keys in files that may be committed)

Best practice: use the environment variable approach. Add export ANTHROPIC_API_KEY=<your-key> to your ~/.bashrc or ~/.zshrc. Never commit a settings.json that contains an API key.

Restricting Claude Code to Specific Directories

By default, Claude Code can read and write any file your user account can access. To restrict it:

Deny patterns for file paths: Use deny rules to block writes to sensitive directories: "Write(.env *)", "Write(config/production/*)"
Run from a subdirectory: Start Claude Code from a subdirectory rather than the project root to limit its default exploration scope
Project-scoped MCP filesystem tool: If you use an MCP filesystem server, configure it with only the allowed paths rather than full filesystem access

Model Selection

The model setting controls which Claude model Claude Code uses. Defaults to the latest recommended model for coding tasks. To override:

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

Use a faster/cheaper model (Haiku, Sonnet) for routine tasks; use a more capable model (Opus) for complex refactoring or architecture tasks. The /model command lets you switch mid-session.

Checklist: Do You Understand This?

Two settings files: global (~/.claude/settings.json) and project-level (.claude/settings.json)
allowedTools: pre-approve tool patterns to avoid per-call prompts — build this up by using "Allow always" during normal sessions
permissions.deny: always-blocked patterns — use for dangerous commands like destructive shell operations
API key: environment variable is the safest approach — never commit keys in settings.json
Restrict file access with deny patterns for sensitive paths; never rely on Claude's judgment alone for production-critical files