Settings Best Practice

Last Updated: Apr 05, 2026 | Claude Code v2.1.92

A comprehensive guide to all available configuration options in Claude Code's settings.json files. As of v2.1.92, Claude Code exposes 60+ settings and 170+ environment variables (use the "env" field in settings.json to avoid wrapper scripts).

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 and managed-mcp.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.

WARNING

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. Also sets the voice dictation language
`cleanupPeriodDays`	number	`30`	Sessions inactive for longer than this period are deleted at startup (minimum 1). Also controls the age cutoff for automatic removal of orphaned subagent worktrees at startup. Setting to `0` is rejected with a validation error. To disable transcript writes in non-interactive mode (`-p`), use `--no-session-persistence` or `persistSession: false` SDK option
`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
`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 built-in commit and PR workflow instructions and the git status snapshot in Claude's system prompt. The `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` environment variable takes precedence over this setting when set
`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`	string	-	Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system on startup. Deep links let external tools open a Claude Code session with a pre-filled prompt via `claude-cli://open?q=...`. The `q` parameter supports multi-line prompts using URL-encoded newlines (`%0A`). Useful in environments where protocol handler registration is restricted or managed separately
`showThinkingSummaries`	boolean	`false`	Show extended thinking summaries in interactive sessions. When unset or `false` (default in interactive mode), thinking blocks are redacted by the API and shown as a collapsed stub. Redaction only changes what you see, not what the model generates -- to reduce thinking spend, lower the budget or disable thinking instead. Non-interactive mode (`-p`) and SDK callers always receive summaries regardless of this setting
`disableSkillShellExecution`	boolean	`false`	Disable inline shell execution for !`...` blocks in skills and custom commands. Commands are replaced with `[shell command execution disabled by policy]`. Bundled and managed skills are not affected (v2.1.91)
`forceRemoteSettingsRefresh`	boolean	`false`	(Managed only) Block CLI startup until remote managed settings are freshly fetched. If the fetch fails, the CLI exits (fail-closed). Use in enterprise environments where policy enforcement must be up-to-date before any session begins (v2.1.92)
`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:

json

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

json

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

json

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

json

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

INFO

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 \| array	Require login to belong to a specific organization. Accepts a single UUID string (which also pre-selects that organization during login) or an array of UUIDs where any listed organization is accepted without pre-selection. When set in managed settings, login fails if the authenticated account does not belong to a listed organization; an empty array fails closed and blocks login with a misconfiguration message

Example:

json

{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh",
  "forceLoginMethod": "console",
  "forceLoginOrgUUID": [
    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
  ]
}

Company Announcements

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

Key	Type	Description
`companyAnnouncements`	array	Array of strings displayed at startup

Example:

json

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

json

{
  "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
`permissions.skipDangerousModePermissionPrompt`	boolean	Skip the confirmation prompt shown before entering bypass permissions mode via `--dangerously-skip-permissions` or `defaultMode: "bypassPermissions"`. Ignored when set in project settings (`.claude/settings.json`) to prevent untrusted repositories from auto-bypassing the prompt
`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 (`--enable-auto-mode`). 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:

json

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

Hook Reference

claude-code-hooks -- Complete hook reference with sound notification system, all 25 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)

json

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

Example:

json

{
  "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`. When set to `false`, the escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing
`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. Also merged with paths from `Edit(...)` allow permission rules. 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. Also merged with paths from `Edit(...)` deny permission rules. Same path prefix conventions as `allowWrite`
`sandbox.filesystem.denyRead`	array	`[]`	Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Also merged with paths from `Read(...)` deny permission rules. 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:

json

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

json

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

json

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

json

{
  "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 left/right 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:

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

INFO

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 the env key:

json

{
  "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
`teammateMode`	string	`"in-process"`	How agent team teammates display: `"auto"` (picks split panes in tmux or iTerm2, in-process otherwise), `"in-process"`, or `"tmux"`. See choose a display mode

Status Line Configuration

json

{
  "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).

json

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

Example:

json

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

json

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

json

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

Environment Variables (via `env`)

Set environment variables for all Claude Code sessions.

json

{
  "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
`CLAUDE_CODE_OAUTH_TOKEN`	OAuth access token for Claude.ai authentication. Alternative to `/login` for SDK and automated environments. Takes precedence over keychain-stored credentials
`CLAUDE_CODE_OAUTH_REFRESH_TOKEN`	OAuth refresh token for Claude.ai authentication. When set, `claude auth login` exchanges this token directly instead of opening a browser. Requires `CLAUDE_CODE_OAUTH_SCOPES`
`CLAUDE_CODE_OAUTH_SCOPES`	Space-separated OAuth scopes the refresh token was issued with (e.g., `"user:profile user:inference user:sessions:claude_code"`). Required when `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` is set
`ANTHROPIC_BASE_URL`	Custom API endpoint
`ANTHROPIC_BEDROCK_BASE_URL`	Override Bedrock endpoint URL
`ANTHROPIC_VERTEX_BASE_URL`	Override Vertex AI endpoint URL
`ANTHROPIC_BETAS`	Comma-separated Anthropic beta header values
`ANTHROPIC_VERTEX_PROJECT_ID`	GCP project ID for Vertex AI
`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_REMOTE_CONTROL_SESSION_NAME_PREFIX`	Prefix for auto-generated Remote Control session names. Defaults to the machine hostname
`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
`API_TIMEOUT_MS`	Timeout in ms for API requests (default: 600000)
`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
`ENABLE_PROMPT_CACHING_1H_BEDROCK`	Request 1-hour cache TTL on Bedrock (`1` to enable)
`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_GLOB_HIDDEN`	Include dotfiles in Glob results (`1` to enable)
`CLAUDE_CODE_GLOB_NO_IGNORE`	Make Glob ignore `.gitignore` patterns (`1` to enable)
`CLAUDE_CODE_GLOB_TIMEOUT_SECONDS`	Timeout in seconds for Glob file discovery
`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_SIMPLE`	Set to `1` to run with a minimal system prompt and only the Bash, file read, and file edit tools
`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_THINKING`	Force-disable extended thinking (`1` to disable)
`DISABLE_INTERLEAVED_THINKING`	Prevent interleaved-thinking beta header from being sent (`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_ENABLE_STREAM_WATCHDOG`	Abort stalled streams (`1` to enable)
`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING`	Enable fine-grained tool streaming (`1` to enable)
`CLAUDE_CODE_DISABLE_AUTO_MEMORY`	Disable auto memory (`1` to disable)
`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`	Disable file checkpointing for `/rewind` (`1` to disable)
`CLAUDE_CODE_DISABLE_ATTACHMENTS`	Disable attachment processing (`1` to disable)
`CLAUDE_CODE_DISABLE_CLAUDE_MDS`	Prevent loading CLAUDE.md files (`1` to disable)
`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`	Auto-resume if previous session ended mid-turn (`1` to enable)
`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`)
`CLAUDE_CODE_TMPDIR`	Override the temp directory used for internal temp files. Claude Code appends `/claude/` to this path. Default: `/tmp` on Unix/macOS, `os.tmpdir()` on Windows
`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_PLUGIN_CACHE_DIR`	Override the plugins root directory
`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`	Skip auto-adding the official marketplace (`1` to disable)
`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`	Wait for plugin install to complete before first query (`1` to enable)
`CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS`	Timeout in ms for synchronous plugin install
`CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE`	Set to `1` to keep the marketplace cache on disk when a `git pull` update fails, instead of deleting and re-cloning (in v2.1.90 changelog, not yet on official env-vars page)
`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_DOCTOR_COMMAND`	Hide the `/doctor` command (`1` to disable)
`DISABLE_LOGIN_COMMAND`	Hide the `/login` command (`1` to disable)
`DISABLE_LOGOUT_COMMAND`	Hide the `/logout` command (`1` to disable)
`DISABLE_UPGRADE_COMMAND`	Hide the `/upgrade` command (`1` to disable)
`DISABLE_EXTRA_USAGE_COMMAND`	Hide the `/extra-usage` command (`1` to disable)
`DISABLE_INSTALL_GITHUB_APP_COMMAND`	Hide the `/install-github-app` command (`1` to disable)
`DISABLE_NON_ESSENTIAL_MODEL_CALLS`	Disable flavor text and non-essential model calls (not in official docs -- unverified)
`CLAUDE_CODE_DEBUG_LOGS_DIR`	Override debug log file directory path
`CLAUDE_CODE_DEBUG_LOG_LEVEL`	Minimum debug log level
`CLAUDE_AUTO_BACKGROUND_TASKS`	Force auto-backgrounding of long tasks (`1` to enable)
`CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP`	Prevent remapping Opus 4.0/4.1 to newer models (`1` to disable)
`FALLBACK_FOR_ALL_PRIMARY_MODELS`	Trigger fallback model for all primary models, not just default (`1` to enable)
`CLAUDE_CODE_GIT_BASH_PATH`	Windows Git Bash executable path (startup-only)
`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_MAX_RETRIES`	Override API request retry count (default: 10)
`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`	Max parallel read-only tools (default: 10)
`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`	Disable built-in subagent types in SDK mode (`1` to disable)
`CLAUDE_AGENT_SDK_MCP_NO_PREFIX`	Skip `mcp__<server>__` prefix for MCP tools in SDK mode (`1` to enable)
`MCP_CONNECTION_NONBLOCKING`	Set to `true` in `-p` mode to skip the MCP connection wait entirely. Bounds `--mcp-config` server connections at 5s instead of blocking on the slowest server (in v2.1.89 changelog, not yet on official env-vars page)
`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_NO_FLICKER`	Set to `1` to enable flicker-free alt-screen rendering. Eliminates visual flicker during fullscreen redraws (v2.1.88)
`CLAUDE_CODE_SCROLL_SPEED`	Mouse wheel scroll multiplier for fullscreen rendering. Increase for faster scrolling, decrease for finer control
`CLAUDE_CODE_DISABLE_MOUSE`	Set to `1` to disable mouse tracking in fullscreen rendering. Useful when mouse events interfere with terminal multiplexers or accessibility tools
`CLAUDE_CODE_ACCESSIBILITY`	Set to `1` to keep native terminal cursor visible for screen readers and accessibility tools
`CLAUDE_CODE_SYNTAX_HIGHLIGHT`	Set to `0` to disable syntax highlighting in diff output
`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`	Skip automatic IDE extension installation (`1` to skip)
`CLAUDE_CODE_AUTO_CONNECT_IDE`	Override auto IDE connection behavior
`CLAUDE_CODE_IDE_HOST_OVERRIDE`	Override IDE host address for connection
`CLAUDE_CODE_IDE_SKIP_VALID_CHECK`	Skip IDE lockfile validation (`1` to skip)
`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`	Debounce interval in ms for OTel headers helper script
`CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS`	Timeout in ms for OpenTelemetry flush
`CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS`	Timeout in ms for OpenTelemetry shutdown
`CLAUDE_STREAM_IDLE_TIMEOUT_MS`	Timeout in ms before the streaming idle watchdog closes a stalled connection. Default: `90000` (90 seconds). Increase if long-running tools or slow networks cause premature timeout errors
`OTEL_LOG_TOOL_DETAILS`	Set to `1` to include `tool_parameters` in OpenTelemetry events. Omitted by default for privacy (in v2.1.85 changelog, not yet on official env-vars page)
`CLAUDE_CODE_MCP_SERVER_NAME`	Name of the MCP server, passed as an environment variable to `headersHelper` scripts so they can generate server-specific authentication headers (in v2.1.85 changelog, not yet on official env-vars page)
`CLAUDE_CODE_MCP_SERVER_URL`	URL of the MCP server, passed as an environment variable to `headersHelper` scripts alongside `CLAUDE_CODE_MCP_SERVER_NAME` (in v2.1.85 changelog, not yet on official env-vars page)
`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`
`DISABLE_AUTO_COMPACT`	Disable automatic context compaction (`1` to disable). Manual `/compact` still works
`DISABLE_COMPACT`	Disable all compaction -- both automatic and manual (`1` to disable)
`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

json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "agent": "code-reviewer",
  "language": "english",
  "cleanupPeriodDays": 30,
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true,
  "showThinkingSummaries": 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"
  }
}

Settings Best Practice ​

Settings Hierarchy ​

Core Configuration ​

General Settings ​

Plans & Memory Directories ​

Worktree Settings ​

Attribution Settings ​

Authentication Helpers ​

Company Announcements ​

Permissions ​

Permission Structure ​

Permission Keys ​

Permission Modes ​

Tool Permission Syntax ​

Hooks ​

MCP Servers ​

MCP Settings ​

MCP Server Matching (Managed Settings) ​

Sandbox ​

Sandbox Settings ​

Plugins ​

Plugin Settings ​

Model Configuration ​

Model Aliases ​

Model Overrides ​

Effort Level ​

Model Environment Variables ​

Display & UX ​

Display Settings ​

Global Config Settings (~/.claude.json) ​

Status Line Configuration ​

File Suggestion Configuration ​

AWS & Cloud Credentials ​

AWS Settings ​

OpenTelemetry ​

Environment Variables (via env) ​

Common Environment Variables ​

Useful Commands ​

Quick Reference: Complete Example ​

Sources ​

Settings Best Practice

Settings Hierarchy

Core Configuration

General Settings

Plans & Memory Directories

Worktree Settings

Attribution Settings

Authentication Helpers

Company Announcements

Permissions

Permission Structure

Permission Keys

Permission Modes

Tool Permission Syntax

Hooks

MCP Servers

MCP Settings

MCP Server Matching (Managed Settings)

Sandbox

Sandbox Settings

Plugins

Plugin Settings

Model Configuration

Model Aliases

Model Overrides

Effort Level

Model Environment Variables

Display & UX

Display Settings

Global Config Settings (`~/.claude.json`)

Status Line Configuration

File Suggestion Configuration

AWS & Cloud Credentials

AWS Settings

OpenTelemetry

Environment Variables (via `env`)

Common Environment Variables

Useful Commands

Quick Reference: Complete Example

Sources