Settings Guide

July 18, 2026 · View on GitHub

Complete reference for configuring Claude Code. Settings control permissions, behavior, and integrations.

Settings Hierarchy (Top Wins)

1. CLI flags              --permission-mode, --max-budget-usd
2. .claude/settings.local.json   Project-local (gitignored)
3. .claude/settings.json         Project-shared (committed)
4. ~/.claude/settings.local.json  User-local (personal)
5. ~/.claude/settings.json        User-global
6. managed-settings.json          Enterprise policy (read-only)

First match wins. Project settings override user settings. CLI flags override everything.

Permission Modes

Mode	Behavior
`default`	Ask for dangerous operations
`acceptEdits`	Auto-approve file edits, ask for shell
`askEdits`	Ask for everything including edits
`dontAsk`	Auto-approve everything (trusted environments)
`viewOnly`	Read-only, no modifications
`bypassPermissions`	Skip all checks (CI/CD only)
`plan`	Research and plan, require approval to execute

Set via CLI: claude --permission-mode plan

Permission Rules

Rules follow Tool or Tool(specifier) format. Evaluated in order: deny > ask > allow.

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)",
      "Edit(/vendor/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(docker *)",
      "Bash(npm publish)"
    ],
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Write",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(ls *)",
      "WebFetch(domain:code.claude.com)",
      "MCP(github:*)",
      "Task(*)",
      "Agent(*)"
    ]
  }
}

Wildcard Syntax

Pattern	Matches
`Bash(npm run *)`	Any npm script
`Edit(/src/**)`	Any file under src/ recursively
`WebFetch(domain:*.github.com)`	Any GitHub subdomain
`MCP(github:*)`	Any tool from github MCP server
`Task(planner)`	Only the planner subagent
`Agent(*)`	Any agent type

Key Settings

Behavior

{
  "outputStyle": "Explanatory",
  "fastMode": false,
  "prefersReducedMotion": false,
  "fileSuggestion": true
}

Output styles: "Concise", "Explanatory", "Learning", "Custom:<instructions>"

Context & Compaction

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"
  }
}

Default auto-compact triggers at ~95%. Set lower for proactive compaction. 50 is good for long sessions.

Plans Directory

{
  "plansDirectory": ".claude/plans"
}

Stores plan mode artifacts for team sharing and review.

Status Line

{
  "statusLine": "model branch tokens"
}

Shows model, git branch, and token usage in the status bar. Customize via /statusline.

Spinner Customization

{
  "spinnerVerbs": ["Thinking", "Analyzing", "Crafting", "Brewing"],
  "spinnerTipsOverride": [
    "Tip: Use /compact at task boundaries",
    "Tip: Plan mode for >3 files",
    "Tip: Ctrl+B sends tasks to background"
  ]
}

Attribution

{
  "attribution": {
    "commitMessage": "",
    "prDescription": ""
  }
}

Set to empty strings to disable "Co-Authored-By" and PR footers.

Sandbox

{
  "sandbox": {
    "filesystem": {
      "allow": ["/home/user/project"],
      "deny": ["/etc", "/root"]
    },
    "network": {
      "allowDomains": ["api.github.com", "registry.npmjs.org"],
      "denyDomains": ["*"]
    }
  }
}

MCP Server Approval

{
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["context7", "playwright"],
  "disabledMcpjsonServers": ["unused-server"]
}

Budget Control

Via CLI flags (not settings.json):

claude --max-budget-usd 5.00
claude --max-turns 50

Production-Ready Example

See settings.example.json in the repo root for a full working configuration.

Scope: What Lives Where

Feature	Global Only	Dual Scope
Tasks & Task Lists	Y
Agent Teams	Y
Auto Memory	Y
Credentials/Auth	Y
Keybindings	Y
MCP User Servers	Y
CLAUDE.md		Y
Settings		Y
Agents		Y
Commands		Y
Skills		Y
Hooks		Y
MCP Project Servers		Y
Rules		Y

Global = ~/.claude/, Project = .claude/

Environment Variables

Key env vars (set in settings or shell):

Variable	Purpose
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	Trigger compaction earlier (default ~95)
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`	Enable agent teams
`CLAUDE_CODE_TMPDIR`	Custom temp directory
`DISABLE_AUTOUPDATER`	Prevent auto-updates
`CLAUDE_CODE_SIMPLE`	Simplified output mode

Cross-Agent Note

Cursor uses .cursor/rules/ and .cursorrules for similar configuration. See references/cross-agent-workflows.md for mapping between Claude Code settings and Cursor rules.