claude-code-best-practice/reports/claude-settings.md

Claude Code Settings Reference

A comprehensive guide to all available configuration options in Claude Code's settings.json files. As of February 2026, Claude Code exposes 38 settings and 84 environment variables (use the "env" field in settings.json to avoid wrapper scripts).

← Back to Claude Code Best Practice

Table of Contents

1. Settings Hierarchy
2. Core Configuration
3. Permissions
4. Hooks
5. MCP Servers
6. Sandbox
7. Plugins
8. Model Configuration
9. Display & UX
10. AWS & Cloud Credentials
11. Environment Variables
12. Useful Commands

---

Settings Hierarchy

Claude Code settings use a 5-level user-writable override chain plus an enforced policy layer:

Priority	Location	Scope	Version Control	Purpose
1	Command line arguments	Session	N/A	Single-session overrides
2	.claude/settings.local.json	Project	No (git-ignored)	Personal project-specific
3	.claude/settings.json	Project	Yes (committed)	Team-shared settings
4	~/.claude/settings.local.json	User	N/A	Personal global overrides
5	~/.claude/settings.json	User	N/A	Global personal defaults

Policy layer: managed-settings.json is organization-enforced and cannot be overridden by local settings.

Important:

• deny rules have highest safety precedence and cannot be overridden by lower-priority allow/ask rules.
• Managed settings may lock or override local behavior even if local files specify different values.

---

Core Configuration

General Settings

Key	Type	Default	Description
model	string	"default"	Override default model. Accepts aliases (sonnet, opus, haiku) or full model IDs
agent	string	-	Set the default agent for the main conversation. Value is the agent name from .claude/agents/. Also available via --agent CLI flag
language	string	"english"	Claude's preferred response language
cleanupPeriodDays	number	30	Sessions inactive longer than this are deleted at startup
autoUpdatesChannel	string	"latest"	Release channel: "stable" or "latest"
alwaysThinkingEnabled	boolean	false	Enable extended thinking by default for all sessions
skipWebFetchPreflight	boolean	false	Skip WebFetch blocklist check before fetching URLs

Example:

{
  "model": "opus",
  "agent": "code-reviewer",
  "language": "japanese",
  "cleanupPeriodDays": 60,
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true
}

Plans Directory

Store plan files in a custom location relative to project root.

Key	Type	Default	Description
plansDirectory	string	.claude/plans/	Directory where /plan outputs are stored

Example:

{
  "plansDirectory": "./my-plans"
}

Use Case: Useful for organizing planning artifacts separately from Claude's internal files, or for keeping plans in a shared team location.

Attribution Settings

Customize attribution messages for git commits and pull requests.

Key	Type	Default	Description
attribution.commit	string	Co-authored-by	Git commit attribution (supports trailers)
attribution.pr	string	Generated message	Pull request description attribution
includeCoAuthoredBy	boolean	true	DEPRECATED - Use attribution instead

Example:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "Generated with Claude Code"
  }
}

Note: Set to empty string ("") to hide attribution entirely.

Authentication Helpers

Scripts for dynamic authentication token generation.

Key	Type	Description
apiKeyHelper	string	Shell script path that outputs auth token (sent as X-Api-Key header)
forceLoginMethod	string	Restrict login to "claudeai" or "console" accounts
forceLoginOrgUUID	string	UUID to automatically select organization during login

Example:

{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh",
  "forceLoginMethod": "console",
  "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Company Announcements

Display custom announcements to users at startup (cycled randomly).

Key	Type	Description
companyAnnouncements	array	Array of strings displayed at startup

Example:

{
  "companyAnnouncements": [
    "Welcome to Acme Corp!",
    "Remember to run tests before committing!",
    "Check the wiki for coding standards"
  ]
}

---

Permissions

Control what tools and operations Claude can perform.

Permission Structure

{
  "permissions": {
    "allow": [],
    "ask": [],
    "deny": [],
    "additionalDirectories": [],
    "defaultMode": "acceptEdits",
    "disableBypassPermissionsMode": "disable"
  }
}

Permission Keys

Key	Type	Description
permissions.allow	array	Rules allowing tool use without prompting
permissions.ask	array	Rules requiring user confirmation
permissions.deny	array	Rules blocking tool use (highest precedence)
permissions.additionalDirectories	array	Extra directories Claude can access
permissions.defaultMode	string	Default permission mode
permissions.disableBypassPermissionsMode	string	Prevent bypass mode activation

Permission Modes

Mode	Behavior
"default"	Standard permission checking with prompts
"acceptEdits"	Auto-accept file edits without asking
"askEdits"	Ask before every operation
"viewOnly"	Read-only mode, no modifications
"bypassPermissions"	Skip all permission checks (dangerous)
"plan"	Read-only exploration mode

Tool Permission Syntax

Tool	Syntax	Examples
Bash	Bash(command pattern)	Bash(npm run *), Bash(* install), Bash(git * main)
Read	Read(path pattern)	Read(.env), Read(./secrets/**)
Edit	Edit(path pattern)	Edit(src/**), Edit(*.ts)
Write	Write(path pattern)	Write(*.md), Write(./docs/**)
NotebookEdit	NotebookEdit(pattern)	NotebookEdit(*)
WebFetch	WebFetch(domain:pattern)	WebFetch(domain:example.com)
WebSearch	WebSearch	Global web search
Task	Task(agent-name)	Task(Explore), Task(my-agent)
Skill	Skill(skill-name)	Skill(weather-fetcher)
MCP	mcp__server__tool	mcp__memory__*, mcp__github__*

Bash wildcard notes:

• * can appear at any position: prefix (Bash(* install)), suffix (Bash(npm *)), or middle (Bash(git * main))
• Bash(*) is treated as equivalent to Bash (matches all bash commands)
• Permission rules support output redirections: Bash(python:*) matches python script.py > output.txt

Example:

{
  "permissions": {
    "allow": [
      "Edit(*)",
      "Write(*)",
      "Bash(npm run *)",
      "Bash(git *)",
      "WebFetch(domain:*)",
      "mcp__*"
    ],
    "ask": [
      "Bash(rm *)",
      "Bash(git push *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ],
    "additionalDirectories": ["../shared-libs/"]
  }
}

---

Hooks

Execute custom shell commands at various points in Claude Code's lifecycle.

Hook Events (16 total)

Event	When Fired	Matcher Support	Common Use Cases
SessionStart	New or resumed session	No	Load context, set environment
SessionEnd	Session terminates	No	Cleanup, logging
UserPromptSubmit	User submits prompt	No	Validate input, add context
PreToolUse	Before tool execution	Yes	Validate commands, modify inputs
PostToolUse	After tool succeeds	Yes	Run linters, verify output
PostToolUseFailure	After tool fails	Yes	Log failures, recovery
PermissionRequest	Permission dialog appears	Yes	Auto-approve/deny patterns
Notification	Notification sent	Yes	Sound alerts, logging
Stop	Claude finishes responding	No	Block/continue decisions
SubagentStart	Subagent spawned	Yes	Per-agent setup
SubagentStop	Subagent completes	Yes	Cleanup, validation
PreCompact	Before context compaction	Yes	Backup, logging
Setup	Repository init (--init, --init-only, --maintenance)	Yes	One-time setup
TeammateIdle	Agent Teams teammate goes idle	Yes	Team orchestration, routing
TaskCompleted	A tracked task is completed	Yes	Progress automation, notifications
ConfigChange	Configuration files change during session	Yes	Enterprise security auditing, blocking settings changes

Hook Configuration Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "script.sh",
            "timeout": 60000,
            "once": true
          }
        ]
      }
    ]
  },
  "disableAllHooks": false,
  "allowManagedHooksOnly": false
}

Hook Properties

Property	Type	Description
matcher	string	Regex pattern to match tool/event (optional)
type	string	"command" or "prompt"
command	string	Shell command to execute (for type: "command")
prompt	string	LLM prompt for evaluation (for type: "prompt")
timeout	number	Timeout in milliseconds
once	boolean	Run only once per session
model	string	Custom model for prompt-based stop hooks (for type: "prompt")

Hook Matcher Patterns

Pattern	Matches
"Bash"	Exact match only
"Edit|Write"	Multiple tools with regex OR
"mcp__.*"	All MCP tools
"mcp__memory__.*"	Specific MCP server tools
"*" or ""	All tools

Hook Exit Codes

Exit Code	Behavior
0	Success, continue
1	Error (logged, continues)
2	Block the operation

Environment Variables in Hooks

Variable	Description
${CLAUDE_PROJECT_DIR}	Project root directory
CLAUDE_TOOL_NAME	Current tool name
CLAUDE_TOOL_INPUT	Tool input (JSON)
CLAUDE_TOOL_OUTPUT	Tool output (PostToolUse only)

PreToolUse/PostToolUse Input Fields:

Field	Description
tool_use_id	Unique identifier for this specific tool invocation

Stop/SubagentStop Input Fields:

The Stop and SubagentStop hooks receive additional fields in their JSON input:

Field	Description
last_assistant_message	The final assistant response text (avoids parsing transcript files)
agent_id	Agent identifier (SubagentStop only)
agent_transcript_path	Path to agent's transcript file (SubagentStop only)

Example:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/validate.py",
            "timeout": 5000
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Session started!'",
            "timeout": 1000,
            "once": true
          }
        ]
      }
    ]
  },
  "disableAllHooks": false
}

---

MCP Servers

Configure Model Context Protocol servers for extended capabilities.

MCP Settings

Key	Type	Scope	Description
enableAllProjectMcpServers	boolean	Any	Auto-approve all .mcp.json servers
enabledMcpjsonServers	array	Any	Allowlist specific server names
disabledMcpjsonServers	array	Any	Blocklist specific server names
allowedMcpServers	array	Managed only	Allowlist with name/command/URL matching
deniedMcpServers	array	Managed only	Blocklist with matching

MCP Server Matching (Managed Settings)

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": "npx @modelcontextprotocol/*" },
    { "serverUrl": "https://mcp.company.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Example:

{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["memory", "github", "filesystem"],
  "disabledMcpjsonServers": ["experimental-server"]
}

---

Sandbox

Configure bash command sandboxing for security.

Sandbox Settings

Key	Type	Default	Description
sandbox.enabled	boolean	false	Enable bash sandboxing
sandbox.autoAllowBashIfSandboxed	boolean	true	Auto-approve bash when sandboxed
sandbox.excludedCommands	array	[]	Commands to run outside sandbox
sandbox.allowUnsandboxedCommands	boolean	true	Allow dangerouslyDisableSandbox
sandbox.ignoreViolations	object	{}	Map of command patterns to path arrays — suppress violation warnings
sandbox.enableWeakerNestedSandbox	boolean	false	Weaker sandbox for Docker (reduces security)
sandbox.network.allowUnixSockets	array	[]	Specific Unix socket paths accessible in sandbox
sandbox.network.allowAllUnixSockets	boolean	false	Allow all Unix sockets (overrides allowUnixSockets)
sandbox.network.allowLocalBinding	boolean	false	Allow binding to localhost ports (macOS)
sandbox.network.allowedDomains	array	[]	Network domain allowlist for sandbox
sandbox.network.deniedDomains	array	[]	Network domain denylist for sandbox
sandbox.network.httpProxyPort	number	-	HTTP proxy port 1-65535 (custom proxy)
sandbox.network.socksProxyPort	number	-	SOCKS5 proxy port 1-65535 (custom proxy)

Example:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker", "gh"],
    "allowUnsandboxedCommands": false,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

---

Plugins

Configure Claude Code plugins and marketplaces.

Plugin Settings

Key	Type	Scope	Description
enabledPlugins	object	Any	Enable/disable specific plugins
extraKnownMarketplaces	object	Any	Add custom plugin marketplaces
strictKnownMarketplaces	array	Managed only	Allowlist of permitted marketplaces
skippedMarketplaces	array	Any	Marketplaces user declined to install
skippedPlugins	array	Any	Plugins user declined to install
pluginConfigs	object	Any	Per-plugin MCP server configs (keyed by plugin@marketplace)

Example:

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "experimental@acme-tools": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

---

Model Configuration

Model Aliases

Alias	Description
"default"	Recommended for your account type
"sonnet"	Latest Sonnet model (Claude Sonnet 4.6)
"opus"	Latest Opus model (Claude Opus 4.6)
"haiku"	Fast Haiku model
"sonnet[1m]"	Sonnet with 1M token context
"opusplan"	Opus for planning, Sonnet for execution

Example:

{
  "model": "opus"
}

Effort Level (Opus 4.6)

When Opus 4.6 is selected, the /model command exposes an effort level control that adjusts how much reasoning the model applies per response. Use the ← → arrow keys in the /model UI to cycle through effort levels.

Effort Level	Description
High (default)	Full reasoning depth, best for complex tasks
Medium	Balanced reasoning, good for everyday tasks
Low	Minimal reasoning, fastest responses

How to use:

1. Run /model in Claude Code
2. Select Default (recommended) — Opus 4.6
3. Use ← → arrow keys to adjust the effort level
4. The setting applies to the current session and future sessions

Note: Effort level is only available for Opus 4.6. Other models (Sonnet, Haiku) do not expose this control.

Model Environment Variables

Configure via env key:

{
  "env": {
    "ANTHROPIC_MODEL": "sonnet",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "custom-haiku-model",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "custom-sonnet-model",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "custom-opus-model",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "MAX_THINKING_TOKENS": "10000"
  }
}

---

Display & UX

Display Settings

Key	Type	Default	Description
statusLine	object	-	Custom status line configuration
outputStyle	string	"default"	Output style (e.g., "Explanatory")
spinnerTipsEnabled	boolean	true	Show tips while waiting
spinnerVerbs	object	-	Custom spinner verbs with mode ("append" or "replace") and verbs array
spinnerTipsOverride	object	-	Custom spinner tips with tips (string array) and optional excludeDefault (boolean)
terminalProgressBarEnabled	boolean	true	Show progress bar in terminal
showTurnDuration	boolean	true	Show turn duration messages
respectGitignore	boolean	true	Respect .gitignore in file picker

Status Line Configuration

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

Status Line Input Fields:

The status line command receives a JSON object on stdin with these notable fields:

Field	Description
workspace.added_dirs	Directories added via /add-dir
context_window.used_percentage	Context window usage percentage
context_window.remaining_percentage	Context window remaining percentage
current_usage	Current context window token count
exceeds_200k_tokens	Whether context exceeds 200k tokens

File Suggestion Configuration

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  },
  "respectGitignore": true
}

Example:

{
  "statusLine": {
    "type": "command",
    "command": "git branch --show-current 2>/dev/null || echo 'no-branch'"
  },
  "spinnerTipsEnabled": true,
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": ["Cooking", "Brewing", "Crafting", "Conjuring"]
  },
  "spinnerTipsOverride": {
    "tips": ["Use /compact at ~50% context", "Start with plan mode for complex tasks"],
    "excludeDefault": true
  },
  "terminalProgressBarEnabled": true,
  "showTurnDuration": false
}

---

AWS & Cloud Credentials

AWS Settings

Key	Type	Description
awsAuthRefresh	string	Script to refresh AWS auth (modifies .aws dir)
awsCredentialExport	string	Script outputting JSON with AWS credentials

Example:

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "awsCredentialExport": "/bin/generate_aws_grant.sh"
}

OpenTelemetry

Key	Type	Description
otelHeadersHelper	string	Script to generate dynamic OpenTelemetry headers

Example:

{
  "otelHeadersHelper": "/bin/generate_otel_headers.sh"
}

---

Environment Variables (via env)

Set environment variables for all Claude Code sessions.

{
  "env": {
    "ANTHROPIC_API_KEY": "...",
    "NODE_ENV": "development",
    "DEBUG": "true"
  }
}

Common Environment Variables

Variable	Description
ANTHROPIC_API_KEY	API key for authentication
ANTHROPIC_AUTH_TOKEN	OAuth token
ANTHROPIC_BASE_URL	Custom API endpoint
CLAUDE_CODE_USE_BEDROCK	Use AWS Bedrock (1 to enable)
CLAUDE_CODE_USE_VERTEX	Use Google Vertex AI (1 to enable)
CLAUDE_CODE_USE_FOUNDRY	Use Microsoft Foundry (1 to enable)
CLAUDE_CODE_ENABLE_TELEMETRY	Enable/disable telemetry (0 or 1)
DISABLE_ERROR_REPORTING	Disable error reporting (1 to disable)
DISABLE_TELEMETRY	Disable telemetry (1 to disable)
MCP_TIMEOUT	MCP startup timeout in ms (default: 10000)
MAX_MCP_OUTPUT_TOKENS	Max MCP output tokens (default: 50000)
BASH_MAX_TIMEOUT_MS	Bash command timeout
BASH_MAX_OUTPUT_LENGTH	Max bash output length
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	Auto-compact threshold percentage (1-100). Default is ~95%. Set lower (e.g., 50) to trigger compaction earlier. Values above 95% have no effect. Use /context to monitor current usage. Example: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 claude
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR	Keep cwd between bash calls (1 to enable)
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS	Disable background tasks (1 to disable)
ENABLE_TOOL_SEARCH	MCP tool search threshold (e.g., auto:5)
DISABLE_PROMPT_CACHING	Disable all prompt caching (1 to disable)
DISABLE_PROMPT_CACHING_HAIKU	Disable Haiku prompt caching
DISABLE_PROMPT_CACHING_SONNET	Disable Sonnet prompt caching
DISABLE_PROMPT_CACHING_OPUS	Disable Opus prompt caching
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS	Disable experimental beta features (1 to disable)
CLAUDE_CODE_SHELL	Override automatic shell detection
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS	Override default file read token limit
CLAUDE_CODE_ENABLE_TASKS	Set to false to disable new task system
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY	Auto-exit SDK mode after idle duration (ms)

---

Useful Commands

Command	Description
/model	Switch models and adjust Opus 4.6 effort level
/config	Interactive configuration UI
/memory	View/edit all memory files
/agents	Manage subagents
/mcp	Manage MCP servers
/hooks	View configured hooks
/plugin	Manage plugins
/keybindings	Configure custom keyboard shortcuts
/skills	View and manage skills
/permissions	View and manage permission rules
--doctor	Diagnose configuration issues
--debug	Debug mode with hook execution details

---

Quick Reference: Complete Example

{
  "model": "sonnet",
  "agent": "code-reviewer",
  "language": "english",
  "cleanupPeriodDays": 30,
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true,
  "plansDirectory": "./plans",

  "permissions": {
    "allow": [
      "Edit(*)",
      "Write(*)",
      "Bash(npm run *)",
      "Bash(git *)",
      "WebFetch(domain:*)",
      "mcp__*"
    ],
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)"
    ],
    "additionalDirectories": ["../shared/"]
  },

  "enableAllProjectMcpServers": true,

  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Tool starting'",
            "timeout": 5000
          }
        ]
      }
    ]
  },
  "disableAllHooks": false,

  "sandbox": {
    "enabled": true,
    "excludedCommands": ["git", "docker"]
  },

  "attribution": {
    "commit": "Generated with Claude Code",
    "pr": ""
  },

  "statusLine": {
    "type": "command",
    "command": "git branch --show-current"
  },

  "spinnerTipsEnabled": true,
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": false
  },
  "showTurnDuration": false,

  "env": {
    "NODE_ENV": "development"
  }
}

---

Sources

• Claude Code Settings Documentation
• Claude Code Settings JSON Schema
• Claude Code Configuration Guide
• Claude Code GitHub Settings Examples
• Eesel AI - Developer's Guide to settings.json
• Shipyard - Claude Code CLI Cheatsheet