Settings Configuration

Overview

Settings control permissions, behavior, output style, and integrations in Claude Code. Configuration follows a hierarchy where more specific settings override broader ones.

Settings Hierarchy

Settings are evaluated in order, with the first match winning:

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

Project settings override user settings. CLI flags override everything. Use .local.json for personal preferences and secrets.

Permission Modes

Control how Claude Code requests approval for operations.

permissionMode

string

default:"default"

Permission level for tool usage

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
claude --permission-mode dontAsk

Permission Rules

Fine-grained control over tool access using allow/deny/ask rules.

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)",
      "Edit(/vendor/**)",
      "Edit(/node_modules/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git reset *)",
      "Bash(docker *)",
      "Bash(npm publish *)",
      "Bash(npx * deploy *)"
    ],
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Write",
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git checkout *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(node *)",
      "Bash(npx jest *)",
      "Bash(npx vitest *)",
      "Bash(npx tsc *)",
      "Bash(npx eslint *)",
      "MCP(github:*)",
      "MCP(context7:*)",
      "Task(*)",
      "Agent(*)"
    ]
  }
}

Wildcard Syntax

Permission rules support glob patterns for flexible matching:

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

Rules are evaluated in order: deny > ask > allow. A denied operation cannot be overridden by allow rules.

Core Settings

Output Style

outputStyle

string

default:"Explanatory"

Controls verbosity and tone of Claude’s responses

"Concise" - Minimal explanations, action-focused
"Explanatory" - Balanced context and detail
"Learning" - Educational mode with extra context
"Custom:<instructions>" - Custom output instructions

{
  "outputStyle": "Concise"
}

Status Line

statusLine

string

default:"model branch tokens"

Configure the status bar displaySpace-separated list of: model, branch, tokens, cost, time

{
  "statusLine": "model branch tokens"
}

Plans Directory

plansDirectory

string

default:".claude/plans"

Directory for storing plan mode artifacts

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

File Suggestion

fileSuggestion

boolean

default:"true"

Enable automatic file suggestions during conversation

Fast Mode

fastMode

boolean

default:"false"

Enable fast mode by default (billed to extra usage)

Reduced Motion

prefersReducedMotion

boolean

default:"false"

Disable animations and spinners for accessibility

Context Management

Auto-Compact Threshold

env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE

string

default:"95"

Trigger automatic compaction at this percentage of context windowLower values (50-80) enable more proactive compaction for long sessions.

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

Why lower the threshold?

Default auto-compact triggers at ~95% context usage. Setting it lower (e.g., 50 or 80) causes Claude to proactively compact context more frequently, which is useful for long sessions or complex codebases.

UI Customization

Spinner Verbs

spinnerVerbs

string[]

Customize loading spinner verbs

{
  "spinnerVerbs": [
    "Thinking",
    "Analyzing",
    "Exploring",
    "Investigating",
    "Crafting",
    "Reviewing"
  ]
}

Spinner Tips

spinnerTipsOverride

string[]

Override default loading tips

{
  "spinnerTipsOverride": [
    "Use /compact at task boundaries to keep context fresh",
    "Shift+Tab cycles modes: Normal > Auto > Plan",
    "Ctrl+B sends the current task to background",
    "Use subagents for parallel exploration",
    "claude -w creates an instant parallel worktree session",
    "Voice mode: /voice then hold spacebar to talk",
    "Esc Esc rewinds to the last checkpoint",
    "Write tests alongside code for better AI output",
    "/doctor diagnoses configuration issues"
  ]
}

Attribution

attribution.commitMessage

string

Template for commit attribution footer

attribution.prDescription

string

Template for pull request attribution footer

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

Set to empty strings to disable “Co-Authored-By” footers in commits and PRs.

Sandbox Configuration

sandbox.filesystem

object

Filesystem access restrictions

sandbox.network

object

Network access restrictions

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

Environment Variables

Key environment variables that affect Claude Code behavior:

Variable	Purpose
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	Trigger compaction earlier (default ~95)
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`	Enable agent teams feature
`CLAUDE_CODE_TMPDIR`	Custom temp directory
`DISABLE_AUTOUPDATER`	Prevent automatic updates
`CLAUDE_CODE_SIMPLE`	Simplified output mode
`CLAUDE_SESSION_ID`	Custom session identifier

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Scope: Global vs Project

Understand what configuration lives where:

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

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

Production Example

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)",
      "Edit(/vendor/**)",
      "Edit(/node_modules/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git reset *)",
      "Bash(docker *)",
      "Bash(npm publish *)",
      "Bash(npx * deploy *)"
    ],
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Write",
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git checkout *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(head *)",
      "Bash(tail *)",
      "Bash(wc *)",
      "Bash(find *)",
      "Bash(grep *)",
      "Bash(node *)",
      "Bash(npx jest *)",
      "Bash(npx vitest *)",
      "Bash(npx tsc *)",
      "Bash(npx eslint *)",
      "MCP(github:*)",
      "MCP(context7:*)",
      "Task(*)",
      "Agent(*)"
    ]
  },
  "outputStyle": "Explanatory",
  "statusLine": "model branch tokens",
  "plansDirectory": ".claude/plans",
  "enableAllProjectMcpServers": false,
  "attribution": {
    "commitMessage": "",
    "prDescription": ""
  },
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"
  },
  "spinnerVerbs": [
    "Thinking",
    "Analyzing",
    "Exploring",
    "Investigating",
    "Crafting",
    "Reviewing"
  ],
  "spinnerTipsOverride": [
    "Use /compact at task boundaries to keep context fresh",
    "Shift+Tab cycles modes: Normal > Auto > Plan",
    "Ctrl+B sends the current task to background",
    "Use subagents for parallel exploration",
    "claude -w creates an instant parallel worktree session",
    "Voice mode: /voice then hold spacebar to talk",
    "Esc Esc rewinds to the last checkpoint",
    "Write tests alongside code for better AI output",
    "/doctor diagnoses configuration issues"
  ]
}

CLI Flags

Override settings with command-line arguments:

# Permission mode
claude --permission-mode plan
claude --permission-mode dontAsk

# Budget control
claude --max-budget-usd 5.00
claude --max-turns 50

# Output mode
claude --print "fix linting errors" --max-turns 10

# Remote access
claude --remote

# Worktree session
claude -w

Next Steps

MCP Servers

Configure Model Context Protocol integrations

Quality Gates

Set up automated validation checks

Model Preferences

Configure task-specific model routing

Get Started

Core Concepts

Skills

Agents

Commands

Hooks & Events

Configuration

Guides

Overview

Settings Hierarchy

Permission Modes

Set via CLI

Permission Rules

Wildcard Syntax

Core Settings

Output Style

Status Line

Plans Directory

File Suggestion

Fast Mode

Reduced Motion

Context Management

Auto-Compact Threshold

UI Customization

Spinner Verbs

Spinner Tips

Attribution

Sandbox Configuration

Environment Variables

Scope: Global vs Project

Production Example

CLI Flags

Next Steps

MCP Servers

Quality Gates

Model Preferences

Build docs developers (and LLMs) love

Get Started

Core Concepts

Skills

Agents

Commands

Hooks & Events

Configuration

Guides

​Overview

​Settings Hierarchy

​Permission Modes

​Set via CLI

​Permission Rules

​Wildcard Syntax

​Core Settings

​Output Style

​Status Line

​Plans Directory

​File Suggestion

​Fast Mode

​Reduced Motion

​Context Management

​Auto-Compact Threshold

​UI Customization

​Spinner Verbs

​Spinner Tips

​Attribution

​Sandbox Configuration

​Environment Variables

​Scope: Global vs Project

​Production Example

​CLI Flags

​Next Steps

MCP Servers

Quality Gates

Model Preferences

Build docs developers (and LLMs) love

Overview

Settings Hierarchy

Permission Modes

Set via CLI

Permission Rules

Wildcard Syntax

Core Settings

Output Style

Status Line

Plans Directory

File Suggestion

Fast Mode

Reduced Motion

Context Management

Auto-Compact Threshold

UI Customization

Spinner Verbs

Spinner Tips

Attribution

Sandbox Configuration

Environment Variables

Scope: Global vs Project

Production Example

CLI Flags

Next Steps