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

Claude Code Settings Reference

A comprehensive guide to all available configuration options in Claude Code's settings.json files. As of v2.1.84, Claude Code exposes 60+ settings and 100+ 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

Settings apply in order of precedence (highest to lowest):

Priority	Location	Scope	Shared?	Purpose
1	Managed settings	Organization	Yes (deployed by IT)	Security policies that cannot be overridden
2	Command line arguments	Session	N/A	Temporary single-session overrides
3	.claude/settings.local.json	Project	No (git-ignored)	Personal project-specific
4	.claude/settings.json	Project	Yes (committed)	Team-shared settings
5	~/.claude/settings.json	User	N/A	Global personal defaults

Managed settings are organization-enforced and cannot be overridden by any other level, including command line arguments. Delivery methods:

• Server-managed settings (remote delivery)
• MDM profiles — macOS plist at com.anthropic.claudecode
• Registry policies — Windows HKLM\SOFTWARE\Policies\ClaudeCode (admin) and HKCU\SOFTWARE\Policies\ClaudeCode (user-level, lowest policy priority)
• File — managed-settings.json (macOS: /Library/Application Support/ClaudeCode/, Linux/WSL: /etc/claude-code/, Windows: C:\Program Files\ClaudeCode\)
• Drop-in directory — managed-settings.d/ alongside managed-settings.json for independent policy fragments (v2.1.83). Following the systemd convention, managed-settings.json is merged first as the base, then all *.json files in the drop-in directory are sorted alphabetically and merged on top. Later files override earlier ones for scalar values; arrays are concatenated and de-duplicated; objects are deep-merged. Hidden files starting with . are ignored. Use numeric prefixes to control merge order (e.g., 10-telemetry.json, 20-security.json)

Within the managed tier, precedence is: server-managed > MDM/OS-level policies > file-based (managed-settings.d/*.json + managed-settings.json) > HKCU registry (Windows only). Only one managed source is used; sources do not merge across tiers. Within the file-based tier, drop-in files and the base file are merged together.

Note: As of v2.1.75, the deprecated Windows fallback path C:\ProgramData\ClaudeCode\managed-settings.json has been removed. Use C:\Program Files\ClaudeCode\managed-settings.json instead.

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.
• Array settings (e.g., permissions.allow) are concatenated and deduplicated across scopes — entries from all levels are combined, not replaced.

---

Core Configuration

General Settings

Key	Type	Default	Description
$schema	string	-	JSON Schema URL for IDE validation and autocompletion (e.g., "https://json.schemastore.org/claude-code-settings.json")
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. Setting to 0 deletes all existing transcripts and disables session persistence entirely (no .jsonl files written, /resume shows no conversations, hooks receive an empty transcript_path)
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 (in JSON schema, not on official settings page)
availableModels	array	-	Restrict which models users can select via /model, --model, Config tool, or ANTHROPIC_MODEL. Does not affect the Default option. Example: ["sonnet", "haiku"]
fastModePerSessionOptIn	boolean	false	Require users to opt in to fast mode each session
teammateMode	string	"auto"	Agent team display mode: "auto" (split panes in tmux/iTerm2, in-process otherwise), "in-process", or "tmux"
defaultShell	string	"bash"	Default shell for input-box ! commands. Accepts "bash" (default) or "powershell". Setting "powershell" routes interactive ! commands through PowerShell on Windows. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (v2.1.84)
includeGitInstructions	boolean	true	Include git-related instructions in system prompt
voiceEnabled	boolean	-	Enable push-to-talk voice dictation. Written automatically when you run /voice. Requires a Claude.ai account
showClearContextOnPlanAccept	boolean	false	Show the "clear context" option on the plan accept screen. Set to true to restore the option (hidden by default since v2.1.81)
disableDeepLinkRegistration	boolean	-	Prevent claude-cli:// protocol handler registration at startup (v2.1.83) (in changelog, not on official settings page)
feedbackSurveyRate	number	-	Probability (0–1) that the session quality survey appears when eligible. Enterprise admins can control how often the survey is shown. Example: 0.05 = 5% of eligible sessions

Example:

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

Plans & Memory Directories

Store plan and auto-memory files in custom locations.

Key	Type	Default	Description
plansDirectory	string	~/.claude/plans	Directory where /plan outputs are stored
autoMemoryDirectory	string	-	Custom directory for auto-memory storage. Accepts ~/-expanded paths. Not accepted in project settings (.claude/settings.json) to prevent redirecting memory writes to sensitive locations; accepted from policy, local, and user settings

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.

Worktree Settings

Configure how --worktree creates and manages git worktrees. Useful for reducing disk usage and startup time in large monorepos.

Key	Type	Default	Description
worktree.symlinkDirectories	array	[]	Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk
worktree.sparsePaths	array	[]	Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk

Example:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

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. In Remote environments, only acceptEdits and plan are honored (v2.1.70+)
permissions.disableBypassPermissionsMode	string	Prevent bypass mode activation
allowManagedPermissionRulesOnly	boolean	(Managed only) Only managed permission rules apply; user/project allow, ask, deny rules are ignored
allow_remote_sessions	boolean	(Managed only) Allow users to start Remote Control and web sessions. Defaults to true. Set to false to prevent remote session access (not in official docs — official permissions page states "Access to Remote Control and web sessions is not controlled by a managed settings key." On Team and Enterprise plans, admins enable/disable via Claude Code admin settings)
autoMode	object	Customize what the auto mode classifier blocks and allows. Contains environment (trusted infrastructure descriptions), allow (exceptions to block rules), and soft_deny (block rules) — all arrays of prose strings. Not read from shared project settings (.claude/settings.json) to prevent repo injection. Available in user, local, and managed settings. Setting allow or soft_deny replaces the entire default list for that section. Run claude auto-mode defaults to see built-in rules before customizing
disableAutoMode	string	Set to "disable" to prevent auto mode from being activated. Removes auto from the Shift+Tab cycle and rejects --permission-mode auto at startup. Can be set at any settings level; most useful in managed settings where users cannot override it
useAutoModeDuringPlan	boolean	Whether plan mode uses auto mode semantics when auto mode is available. Default: true. Not read from shared project settings (.claude/settings.json). Appears in /config as "Use auto mode during plan"

Permission Modes

Mode	Behavior
"default"	Standard permission checking with prompts
"acceptEdits"	Auto-accept file edits without asking
"askEdits"	Ask before every operation (not in official docs — unverified)
"dontAsk"	Auto-denies tools unless pre-approved via /permissions or permissions.allow rules
"viewOnly"	Read-only mode, no modifications (not in official docs — unverified)
"bypassPermissions"	Skip all permission checks (dangerous)
"auto"	Background classifier replaces manual prompts. Research preview — requires Team plan + Sonnet/Opus 4.6. Classifier auto-approves read-only and file edits; sends everything else through a safety check. Falls back to prompting after 3 consecutive or 20 total blocks. Configure with autoMode setting
"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)
Agent	Agent(name)	Agent(researcher), Agent(*) — permission scoped to subagent spawning
Skill	Skill(skill-name)	Skill(weather-fetcher)
MCP	mcp__server__tool or MCP(server:tool)	mcp__memory__*, MCP(github:*)

Evaluation order: Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins.

Read/Edit path patterns: Permission rules for Read, Edit, and Write support gitignore-style patterns with four prefix types:

Prefix	Meaning	Example
//	Absolute path from filesystem root	Read(//Users/alice/file)
~/	Relative to home directory	Read(~/.zshrc)
/	Relative to project root	Edit(/src/**)
./ or none	Relative path (current directory)	Read(.env), Read(*.ts)

Bash wildcard notes:

• * can appear at any position: prefix (Bash(* install)), suffix (Bash(npm *)), or middle (Bash(git * main))
• Word boundary: Bash(ls *) (space before *) matches ls -la but NOT lsof; Bash(ls*) (no space) matches both
• Bash(*) is treated as equivalent to Bash (matches all bash commands)
• Permission rules support output redirections: Bash(python:*) matches python script.py > output.txt
• The legacy :* suffix syntax (e.g., Bash(npm:*)) is equivalent to * but is deprecated

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

Hook configuration (events, properties, matchers, exit codes, environment variables, and HTTP hooks) is maintained in a dedicated repository:

claude-code-hooks — Complete hook reference with sound notification system, all 19 hook events, HTTP hooks, matcher patterns, exit codes, and environment variables.

Hook-related settings keys (hooks, disableAllHooks, allowManagedHooksOnly, allowedHttpHookUrls, httpHookAllowedEnvVars) are documented there.

For the official hooks reference, see the Claude Code Hooks Documentation.

---

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
allowManagedMcpServersOnly	boolean	Managed only	Only allow MCP servers explicitly listed in managed allowlist
channelsEnabled	boolean	Managed only	Allow channels for Team and Enterprise users. When unset or false, channel message delivery is blocked regardless of --channels flag
allowedChannelPlugins	array	Managed only	Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Undefined = fall back to the default, empty array = block all channel plugins. Requires channelsEnabled: true. Each entry is an object with marketplace and plugin fields (v2.1.84)

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.failIfUnavailable	boolean	false	Exit with error when sandbox is enabled but cannot start, instead of running unsandboxed. Useful for enterprise policies that require strict sandboxing (v2.1.83)
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 (in JSON schema, not on official settings page)
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 (not in official docs — unverified)
sandbox.network.httpProxyPort	number	-	HTTP proxy port 1-65535 (custom proxy)
sandbox.network.socksProxyPort	number	-	SOCKS5 proxy port 1-65535 (custom proxy)
sandbox.network.allowManagedDomainsOnly	boolean	false	Only allow domains in managed allowlist (managed settings)
sandbox.filesystem.allowWrite	array	[]	Additional paths where sandboxed commands can write. Arrays are merged across all settings scopes. Prefix: / (absolute), ~/ (home), ./ or none (project-relative in project settings, ~/.claude-relative in user settings). The older // prefix for absolute paths still works. Note: This differs from Read/Edit permission rules, which use // for absolute and / for project-relative
sandbox.filesystem.denyWrite	array	[]	Paths where sandboxed commands cannot write. Arrays are merged across all settings scopes. Same path prefix conventions as allowWrite
sandbox.filesystem.denyRead	array	[]	Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Same path prefix conventions as allowWrite
sandbox.filesystem.allowRead	array	[]	Paths to re-allow read access within denyRead regions. Takes precedence over denyRead. Arrays are merged across all settings scopes. Same path prefix conventions as allowWrite
sandbox.filesystem.allowManagedReadPathsOnly	boolean	false	(Managed only) Only allowRead paths from managed settings are respected. allowRead entries from user, project, and local settings are ignored
sandbox.enableWeakerNetworkIsolation	boolean	false	(macOS only) Allow access to system TLS trust (com.apple.trustd.agent); reduces security

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	Project	Add custom plugin marketplaces (team sharing via .claude/settings.json)
strictKnownMarketplaces	array	Managed only	Allowlist of permitted marketplaces
skippedMarketplaces	array	Any	Marketplaces user declined to install (in JSON schema, not on official settings page)
skippedPlugins	array	Any	Plugins user declined to install (in JSON schema, not on official settings page)
pluginConfigs	object	Any	Per-plugin MCP server configs (keyed by plugin@marketplace) (in JSON schema, not on official settings page)
blockedMarketplaces	array	Managed only	Block specific plugin marketplaces
pluginTrustMessage	string	Managed only	Custom message displayed when prompting users to trust plugins

Marketplace source types: github, git, directory, hostPattern, settings, url, npm, file. Use source: 'settings' to declare a small set of plugins inline without setting up a hosted marketplace repository.

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"
      }
    },
    "inline-tools": {
      "source": {
        "source": "settings",
        "name": "inline-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": { "source": "github", "repo": "acme-corp/code-formatter" }
          }
        ]
      }
    }
  }
}

---

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
"opus[1m]"	Opus with 1M token context (default on Max, Team, and Enterprise since v2.1.75)
"opusplan"	Opus for planning, Sonnet for execution

Example:

{
  "model": "opus"
}

Model Overrides

Map Anthropic model IDs to provider-specific model IDs for Bedrock, Vertex, or Foundry deployments.

Key	Type	Default	Description
effortLevel	string	-	Persist the effort level across sessions. Accepts "low", "medium", or "high". Written automatically when you run /effort low, /effort medium, or /effort high. Supported on Opus 4.6 and Sonnet 4.6
modelOverrides	object	-	Map model picker entries to provider-specific IDs (e.g., Bedrock inference profile ARNs). Each key is a model picker entry name, each value is the provider model ID

Example:

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789:inference-profile/anthropic.claude-opus-4-6-v1:0",
    "claude-sonnet-4-6": "arn:aws:bedrock:us-east-1:123456789:inference-profile/anthropic.claude-sonnet-4-6-v1:0"
  }
}

Effort Level

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	Full reasoning depth, best for complex tasks
Medium (default)	Balanced reasoning, good for everyday tasks
Low	Minimal reasoning, fastest responses

How to use:

1. Run /effort low, /effort medium, or /effort high to set directly (v2.1.76+)
2. Or run /model → select a model → use ← → arrow keys to adjust
3. The setting persists via the effortLevel key in settings.json

Note: Effort level is available for Opus 4.6 and Sonnet 4.6 on Max and Team plans. The default was changed from High to Medium in v2.1.68. As of v2.1.75, 1M context window for Opus 4.6 is available by default on Max, Team, and Enterprise plans.

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)
respectGitignore	boolean	true	Respect .gitignore in file picker
prefersReducedMotion	boolean	false	Reduce animations and motion effects in the UI
fileSuggestion	object	-	Custom file suggestion command (see File Suggestion Configuration below)

Global Config Settings (~/.claude.json)

These display preferences are stored in ~/.claude.json, not settings.json. Adding them to settings.json will trigger a schema validation error.

Key	Type	Default	Description
autoConnectIde	boolean	false	Automatically connect to a running IDE when Claude Code starts from an external terminal. Appears in /config as Auto-connect to IDE (external terminal) when running outside a VS Code or JetBrains terminal
autoInstallIdeExtension	boolean	true	Automatically install the Claude Code IDE extension when running from a VS Code terminal. Appears in /config as Auto-install IDE extension. Can also be disabled via CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL env var
editorMode	string	"normal"	Key binding mode for the input prompt: "normal" or "vim". Written automatically when you run /vim. Appears in /config as Key binding mode
showTurnDuration	boolean	true	Show turn duration messages after responses (e.g., "Cooked for 1m 6s"). Edit ~/.claude.json directly to change
terminalProgressBarEnabled	boolean	true	Show the terminal progress bar in supported terminals (ConEmu, Ghostty 1.2.0+, and iTerm2 3.6.6+). Appears in /config as Terminal progress bar

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
rate_limits.five_hour.used_percentage	Five-hour rate limit usage percentage (v2.1.80+)
rate_limits.five_hour.resets_at	Five-hour rate limit reset timestamp
rate_limits.seven_day.used_percentage	Seven-day rate limit usage percentage
rate_limits.seven_day.resets_at	Seven-day rate limit reset timestamp

File Suggestion Configuration

The file suggestion script receives a JSON object on stdin (e.g., {"query": "src/comp"}) and must output up to 15 file paths (one per line).

{
  "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
  }
}

---

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
ANTHROPIC_CUSTOM_MODEL_OPTION	Model ID to add as a custom entry in the /model picker. Use to make a non-standard or gateway-specific model selectable without replacing built-in aliases
ANTHROPIC_CUSTOM_MODEL_OPTION_NAME	Display name for the custom model entry in the /model picker. Defaults to the model ID when not set
ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION	Display description for the custom model entry in the /model picker. Defaults to Custom model (<model-id>) when not set
ANTHROPIC_MODEL	Name of the model to use. Accepts aliases (sonnet, opus, haiku) or full model IDs. Overrides the model setting
ANTHROPIC_DEFAULT_HAIKU_MODEL	Override the Haiku model alias with a custom model ID (e.g., for third-party deployments)
ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME	Customize the Haiku entry label in the /model picker when using a pinned model on Bedrock/Vertex/Foundry. Defaults to the model ID
ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION	Customize the Haiku entry description in the /model picker. Defaults to Custom model (<model-id>)
ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES	Override capability detection for a pinned Haiku model. Comma-separated values (e.g., effort,thinking). Required when the pinned model supports features the auto-detection cannot confirm
CLAUDECODE	Set to 1 in shell environments Claude Code spawns (Bash tool, tmux sessions). Not set in hooks or status line commands. Use to detect when a script is running inside a Claude Code shell
CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS	Set to 1 to allow fast mode when the organization status check fails due to a network error. Useful when a corporate proxy blocks the status 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_USE_POWERSHELL_TOOL	Set to 1 to enable the PowerShell tool on Windows (opt-in preview). When enabled, Claude can run PowerShell commands natively instead of routing through Git Bash. Only supported on native Windows, not WSL (v2.1.84)
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
MAX_MCP_OUTPUT_TOKENS	Max MCP output tokens (default: 25000). Warning displayed when output exceeds 10,000 tokens
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 true to enable task tracking in non-interactive mode (-p flag). Tasks are on by default in interactive mode
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY	Auto-exit SDK mode after idle duration (ms)
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING	Disable adaptive thinking (1 to disable)
CLAUDE_CODE_DISABLE_1M_CONTEXT	Disable 1M token context window (1 to disable)
CLAUDE_CODE_ACCOUNT_UUID	Override account UUID for authentication
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS	Disable git-related system prompt instructions
CLAUDE_CODE_NEW_INIT	Set to true to make /init run an interactive setup flow. Asks which files to generate (CLAUDE.md, skills, hooks) before exploring the codebase. Without this, /init generates a CLAUDE.md automatically
CLAUDE_CODE_PLUGIN_SEED_DIR	Path to one or more read-only plugin seed directories, separated by : on Unix or ; on Windows. Bundle pre-populated plugins into a container image. Claude Code registers marketplaces from these directories at startup and uses pre-cached plugins without re-cloning
ENABLE_CLAUDEAI_MCP_SERVERS	Enable Claude.ai MCP servers
CLAUDE_CODE_EFFORT_LEVEL	Set effort level: low, medium, high, max (Opus 4.6 only), or auto (use model default). Takes precedence over /effort and the effortLevel setting
CLAUDE_CODE_MAX_TURNS	Maximum agentic turns before stopping (not in official docs — unverified)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	Equivalent of setting DISABLE_AUTOUPDATER, DISABLE_FEEDBACK_COMMAND, DISABLE_ERROR_REPORTING, and DISABLE_TELEMETRY
CLAUDE_CODE_SKIP_SETTINGS_SETUP	Skip first-run settings setup flow (not in official docs — unverified)
CLAUDE_CODE_PROMPT_CACHING_ENABLED	Override prompt caching behavior (not in official docs — unverified)
CLAUDE_CODE_DISABLE_TOOLS	Comma-separated list of tools to disable (not in official docs — unverified)
CLAUDE_CODE_DISABLE_MCP	Disable all MCP servers (1 to disable) (not in official docs — unverified)
CLAUDE_CODE_MAX_OUTPUT_TOKENS	Max output tokens per response. Default: 32,000 (64,000 for Opus 4.6 as of v2.1.77). Upper bound: 64,000 (128,000 for Opus 4.6 and Sonnet 4.6 as of v2.1.77)
CLAUDE_CODE_DISABLE_FAST_MODE	Disable fast mode entirely (1 to disable)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK	Set to 1 to disable the non-streaming fallback when a streaming request fails mid-stream. Streaming errors propagate to the retry layer instead. Useful when a proxy or gateway causes the fallback to produce duplicate tool execution (v2.1.83)
CLAUDE_CODE_DISABLE_AUTO_MEMORY	Disable auto memory (1 to disable)
CLAUDE_CODE_USER_EMAIL	Provide user email synchronously for authentication
CLAUDE_CODE_ORGANIZATION_UUID	Provide organization UUID synchronously for authentication
CLAUDE_CONFIG_DIR	Custom config directory (overrides default ~/.claude)
ANTHROPIC_CUSTOM_HEADERS	Custom headers for API requests (Name: Value format, newline-separated for multiple headers)
ANTHROPIC_FOUNDRY_API_KEY	API key for Microsoft Foundry authentication
ANTHROPIC_FOUNDRY_BASE_URL	Base URL for Foundry resource
ANTHROPIC_FOUNDRY_RESOURCE	Foundry resource name
AWS_BEARER_TOKEN_BEDROCK	Bedrock API key for authentication
ANTHROPIC_SMALL_FAST_MODEL	DEPRECATED — Use ANTHROPIC_DEFAULT_HAIKU_MODEL instead
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION	AWS region for deprecated Haiku-class model override
CLAUDE_CODE_SHELL_PREFIX	Command prefix prepended to bash commands
BASH_DEFAULT_TIMEOUT_MS	Default bash command timeout in ms
CLAUDE_CODE_SKIP_BEDROCK_AUTH	Skip AWS auth for Bedrock (1 to skip)
CLAUDE_CODE_SKIP_FOUNDRY_AUTH	Skip Azure auth for Foundry (1 to skip)
CLAUDE_CODE_SKIP_VERTEX_AUTH	Skip Google auth for Vertex (1 to skip)
CLAUDE_CODE_PROXY_RESOLVES_HOSTS	Allow proxy to perform DNS resolution
CLAUDE_CODE_API_KEY_HELPER_TTL_MS	Credential refresh interval in ms for apiKeyHelper
CLAUDE_CODE_CLIENT_CERT	Client certificate path for mTLS
CLAUDE_CODE_CLIENT_KEY	Client private key path for mTLS
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE	Passphrase for encrypted mTLS key
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS	Plugin marketplace git clone timeout in ms (default: 120000)
CLAUDE_CODE_HIDE_ACCOUNT_INFO	Hide email/org info from UI (not in official docs — unverified)
CLAUDE_CODE_DISABLE_CRON	Disable scheduled/cron tasks (1 to disable)
DISABLE_INSTALLATION_CHECKS	Disable installation warnings
DISABLE_FEEDBACK_COMMAND	Disable the /feedback command. The older name DISABLE_BUG_COMMAND is also accepted
DISABLE_NON_ESSENTIAL_MODEL_CALLS	Disable flavor text and non-essential model calls (not in official docs — unverified)
DISABLE_COST_WARNINGS	Disable cost warning messages
CLAUDE_CODE_SUBAGENT_MODEL	Override model for subagents (e.g., haiku, sonnet)
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB	Set to 1 to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers). Use for defense-in-depth when subprocesses should not inherit API keys (v2.1.83)
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS	SessionEnd hook timeout in ms (replaces hard 1.5s limit)
CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY	Disable feedback survey prompts (1 to disable)
CLAUDE_CODE_DISABLE_TERMINAL_TITLE	Disable terminal title updates (1 to disable)
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL	Skip automatic IDE extension installation (1 to skip)
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS	Debounce interval in ms for OTel headers helper script
ANTHROPIC_DEFAULT_OPUS_MODEL	Override Opus model alias (e.g., claude-opus-4-6[1m])
ANTHROPIC_DEFAULT_OPUS_MODEL_NAME	Customize the Opus entry label in the /model picker when using a pinned model on Bedrock/Vertex/Foundry. Defaults to the model ID
ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION	Customize the Opus entry description in the /model picker. Defaults to Custom model (<model-id>)
ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES	Override capability detection for a pinned Opus model. Comma-separated values (e.g., effort,thinking). Required when the pinned model supports features the auto-detection cannot confirm
ANTHROPIC_DEFAULT_SONNET_MODEL	Override Sonnet model alias (e.g., claude-sonnet-4-6)
ANTHROPIC_DEFAULT_SONNET_MODEL_NAME	Customize the Sonnet entry label in the /model picker when using a pinned model on Bedrock/Vertex/Foundry. Defaults to the model ID
ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION	Customize the Sonnet entry description in the /model picker. Defaults to Custom model (<model-id>)
ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES	Override capability detection for a pinned Sonnet model. Comma-separated values (e.g., effort,thinking). Required when the pinned model supports features the auto-detection cannot confirm
MAX_THINKING_TOKENS	Maximum extended thinking tokens per response
CLAUDE_CODE_AUTO_COMPACT_WINDOW	Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window (200K standard, 1M for extended context models). Use a lower value (e.g., 500000) on a 1M model to treat it as 500K for compaction. Capped at actual context window. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is applied as a percentage of this value. Setting this decouples the compaction threshold from the status line's used_percentage
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION	Enable prompt suggestions
CLAUDE_CODE_PLAN_MODE_REQUIRED	Require plan mode for sessions
CLAUDE_CODE_TEAM_NAME	Team name for agent teams
CLAUDE_CODE_TASK_LIST_ID	Task list ID for task integration
CLAUDE_ENV_FILE	Custom environment file path
FORCE_AUTOUPDATE_PLUGINS	Force plugin auto-updates (1 to enable)
HTTP_PROXY	HTTP proxy URL for network requests
HTTPS_PROXY	HTTPS proxy URL for network requests
NO_PROXY	Comma-separated list of hosts that bypass proxy
MCP_TOOL_TIMEOUT	MCP tool execution timeout in ms
MCP_CLIENT_SECRET	MCP OAuth client secret
MCP_OAUTH_CALLBACK_PORT	MCP OAuth callback port
IS_DEMO	Enable demo mode
SLASH_COMMAND_TOOL_CHAR_BUDGET	Character budget for slash command tool output
VERTEX_REGION_CLAUDE_3_5_HAIKU	Vertex AI region override for Claude 3.5 Haiku
VERTEX_REGION_CLAUDE_3_7_SONNET	Vertex AI region override for Claude 3.7 Sonnet
VERTEX_REGION_CLAUDE_4_0_OPUS	Vertex AI region override for Claude 4.0 Opus
VERTEX_REGION_CLAUDE_4_0_SONNET	Vertex AI region override for Claude 4.0 Sonnet
VERTEX_REGION_CLAUDE_4_1_OPUS	Vertex AI region override for Claude 4.1 Opus

---

Useful Commands

Command	Description
/model	Switch models and adjust Opus 4.6 effort level
/effort	Set effort level directly: low, medium, high (v2.1.76+)
/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

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "agent": "code-reviewer",
  "language": "english",
  "cleanupPeriodDays": 30,
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true,
  "includeGitInstructions": true,
  "defaultShell": "bash",
  "plansDirectory": "./plans",
  "effortLevel": "medium",

  "worktree": {
    "symlinkDirectories": ["node_modules"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  },

  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789:inference-profile/anthropic.claude-opus-4-6-v1:0"
  },

  "autoMode": {
    "environment": [
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted internal domains: *.internal.example.com"
    ]
  },

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

  "enableAllProjectMcpServers": true,

  "sandbox": {
    "enabled": true,
    "excludedCommands": ["git", "docker"],
    "filesystem": {
      "denyRead": ["./secrets/"],
      "denyWrite": ["./.env"]
    }
  },

  "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
  },
  "prefersReducedMotion": false,

  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_EFFORT_LEVEL": "medium"
  }
}

---

Sources

• Claude Code Settings Documentation
• Claude Code Settings JSON Schema
• Claude Code Changelog
• Claude Code GitHub Settings Examples
• Eesel AI - Developer's Guide to settings.json
• Shipyard - Claude Code CLI Cheatsheet
• Claude Code Environment Variables Reference
• Claude Code Permissions Reference