# Claude Code Configuration ## Scopes Claude Code's configuration may be defined at different levels: - Local (default) - User - Project ## Settings files Settings (parameters, themes, and environment variables) are stored at different levels: - Global: `~/.claude/settings.json` - Project-level: `.claude/settings.json` and `.claude/settings.local.json` (for settings that need to be ignored by git) Enterprise deployments support managed policy settings: https://docs.anthropic.com/en/docs/claude-code/settings#settings-files Settings are applied using the following order of precedence: 1. Enterprise policies 2. Command-line arguments 3. Local project settings 4. Shared project settings 5. User settings ## Key settings - `cleanupPeriodDays`: How long to locally retain chat transcripts (default: 30 days) - `env`: Environment variables applied to all sessions. Grouped below for navigation; full list: https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables - **Auth & model** - `ANTHROPIC_API_KEY` (direct API authentication) - `ANTHROPIC_AUTH_TOKEN` (custom Authorization header value) - `ANTHROPIC_CUSTOM_HEADERS` (additional request headers, format `"Header: value"`) - `ANTHROPIC_MODEL` (override default model, e.g. `claude-opus-4-7`) - `CLAUDE_CODE_SUBAGENT_MODEL` (separate model for subagents — key cost lever; pair Opus main + Haiku/Sonnet subagents) - `CLAUDE_CODE_MAX_OUTPUT_TOKENS` (cap output length per response) - **Cloud providers** (one of) - `CLAUDE_CODE_USE_BEDROCK=1` + `AWS_REGION` + optional `ANTHROPIC_BEDROCK_BASE_URL`, `ANTHROPIC_BEDROCK_SERVICE_TIER` (`default` | `flex` | `priority`) - `CLAUDE_CODE_USE_VERTEX=1` + `CLOUD_ML_REGION` + `ANTHROPIC_VERTEX_PROJECT_ID` - `CLAUDE_CODE_USE_FOUNDRY=1` (Microsoft Foundry) - **Telemetry / non-essential traffic** - `CLAUDE_CODE_ENABLE_TELEMETRY` (set to 0 to disable telemetry) - `DISABLE_TELEMETRY` (set to 1 to opt out of Statsig telemetry) - `DISABLE_ERROR_REPORTING` (set to 1 to disable Sentry error reporting) - `DISABLE_FEEDBACK_COMMAND` (set to 1 to disable the `/feedback` command upload) - `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` (set to 1 to disable the "How is Claude doing this session?" rating prompt) - `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` (set to 1 to opt out of ALL non-essential traffic at once: Statsig telemetry, Sentry error reporting, `/feedback` reports, and session quality surveys. Equivalent to setting `DISABLE_TELEMETRY=1`, `DISABLE_ERROR_REPORTING=1`, `DISABLE_FEEDBACK_COMMAND=1`, and `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` together. Does NOT affect the WebFetch domain safety check — that has its own opt-out via `skipWebFetchPreflight: true` in settings. Bedrock/Vertex/Foundry already have telemetry/error/feedback default-off, so this var mainly matters when using the Claude API directly.) - `DISABLE_COST_WARNINGS` (set to 1 to hide cost warnings) - **Updates** - `DISABLE_AUTOUPDATER` (set to 1 to disable auto updates) - `DISABLE_UPDATES` (set to 1 to block ALL update paths — stricter than `DISABLE_AUTOUPDATER`) - **Prompt caching** - `DISABLE_PROMPT_CACHING` (set to 1 to disable caching globally) - `ENABLE_PROMPT_CACHING_1H` (opt into 1-hour cache TTL) - `FORCE_PROMPT_CACHING_5M` (force 5-minute cache TTL) - **Tool timeouts & limits** (often the fix when Bash/MCP hangs) - `BASH_DEFAULT_TIMEOUT_MS` (default Bash command timeout) - `BASH_MAX_TIMEOUT_MS` (maximum Bash timeout) - `BASH_MAX_OUTPUT_LENGTH` (Bash output truncation limit) - `MCP_TIMEOUT` (MCP server startup timeout) - `MCP_TOOL_TIMEOUT` (MCP tool execution timeout) - `MAX_MCP_OUTPUT_TOKENS` (cap MCP tool output) - **Network / corporate environments** - `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` (standard proxy vars) - `CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY` (mTLS client certificate paths) - **UI / terminal** - `CLAUDE_CODE_NO_FLICKER` (set to 1 to enable the experimental no-flicker renderer; eliminates terminal flicker and supports mouse events): `CLAUDE_CODE_NO_FLICKER=1 claude` - `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` (don't update the terminal title) - `CLAUDE_CODE_HIDE_CWD` (hide working directory in startup banner) - `CLAUDE_CODE_SHELL` (override shell detection, e.g. `/bin/zsh`) - `CLAUDE_CODE_TMPDIR` (override temp directory) - `USE_BUILTIN_RIPGREP` (use bundled ripgrep instead of system one) - `CLAUDE_CODE_USE_POWERSHELL_TOOL` (Windows: enable PowerShell tool, v2.1.111+) - `CLAUDE_CODE_GIT_BASH_PATH` (Windows: explicit path to Git Bash, v2.1.98+) - **Behavior tweaks** - `CLAUDE_CODE_SIMPLE` (set to 1 to run Anthropic's take on the simplest harness — strips advanced scaffolding and gives you a minimal Claude Code experience): `CLAUDE_CODE_SIMPLE=1 claude` - `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` (set to 1 to opt out of adaptive thinking and revert to fixed thinking budgets) - `CLAUDE_CODE_DISABLE_AUTO_MEMORY` (set to 1 to disable auto memory — see [[Claude Code Memory]]) - `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` (set to 1 to drop the built-in git workflow guidance from the system prompt) - `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` (control session recap on resume — set 0 to disable, 1 to force) - `CLAUDE_CODE_DISABLE_1M_CONTEXT` (use standard 200K context only, not 1M) - `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` (configure SessionEnd hook timeout, v2.1.121+) - `CLAUDE_CODE_REMOTE` (set to `true` in cloud sessions; check in SessionStart hooks to skip local-only setup) - `CLAUDE_ENV_FILE` (path to file that SessionStart hooks can write to for persisting env vars into subsequent Bash commands) - `CLAUDE_CODE_IDE_AUTO_CONNECT` (default `true`; set false to skip auto-connect to IDE) - `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` (set 1 to suppress IDE extension install prompt) - **Debugging & observability** - `ANTHROPIC_LOG=debug` (enable API request logging) - `OTEL_LOGS_EXPORTER`, `OTEL_METRICS_EXPORTER`, `OTEL_TRACES_EXPORTER` (set to `none` to disable, or configure exporters) - `OTEL_LOG_TOOL_CONTENT=1` (emit tool input/output in OTel spans) - `OTEL_LOG_USER_PROMPTS=1` (emit user prompts in OTel traces) - `TRACEPARENT` (W3C Trace Context parent — for distributed tracing) - `permissions`: define allow/deny rules (see [[Claude Code Permissions]]) - `preferredNotifChannel`: how Claude Code should notify you - `terminal_bell`: terminal sound - `showThinkingSummaries`: whether to show thinking blocks in the output. Since 2.1.69+, hidden by default via a beta header that tells the API to skip thinking summaries, which reduces latency. This is a UI-only change; it does not affect thinking itself, thinking budgets, or how extended reasoning works under the hood. Re-enable: `"showThinkingSummaries": true` in `~/.claude/settings.json`. Note: when hidden, locally stored transcripts won't contain raw thinking, which can mislead transcript analysis tools into believing thinking depth dropped - `verbose`: whether to show full Bash and command outputs (default: false) ## Skill listing budget Two top-level keys control how the auto-generated skill listing is fitted into context. They're not in the public settings reference (verified against the v2.1.129 binary schema) but are accepted in `~/.claude/settings.json`. - `skillListingBudgetFraction` (number; > 0, ≤ 1; default `0.01`): fraction of the context window (in characters) reserved for the skill listing sent to Claude. When the listing exceeds the budget, descriptions are shortened to fit. Raise to opt in to higher per-turn context cost; lower to claw context back. With ~400 skills, 0.01 (~10k chars at 1M context) is often too tight and triggers truncation; 0.02–0.03 is a reasonable bump. Claude Code's UI also surfaces this key in its "your skill listing was truncated" warning. - `skillListingMaxDescChars` (positive integer; default `1536`): per-skill description character cap in the listing. Descriptions longer than this are truncated regardless of the global budget. Raise for skills that need richer trigger descriptions to be matched. - `SLASH_COMMAND_TOOL_CHAR_BUDGET` (env var) overrides both above when set; takes precedence over `skillListingBudgetFraction` calculations. ## Additional top-level settings (not in public docs) Surfaced from the v2.1.129 binary schema. All are top-level keys in `~/.claude/settings.json` (or project/local equivalents) unless noted. ### Notifications & UI - `agentPushNotifEnabled` (boolean): allow Claude to push proactive mobile notifications. - `inputNeededNotifEnabled` (boolean): push to mobile when a permission prompt or question is waiting. - `spinnerTipsEnabled` (boolean): whether to show tips in the spinner. - `hideVimModeIndicator` (boolean): hide the built-in `-- INSERT --` / `-- VISUAL --` indicator below the prompt. Use when a status line script renders `vim.mode` itself. - `editorMode` (enum): key binding mode for the prompt input. - `outputStyle` (string): named output style for assistant responses. - `preferredNotifChannel` (enum): preferred OS notification channel (replaces the older `preferredNotifChannel: terminal_bell` shape). ### Auto-memory & compaction - `autoMemoryEnabled` (boolean): enable [[Claude Code Memory|auto-memory]] for the project. False = no read/write to the auto-memory dir. - `autoMemoryDirectory` (string): custom path; supports `~/`. Ignored if set in checked-in `.claude/settings.json` (security). Defaults to `~/.claude/projects/<sanitized-cwd>/memory/`. - `autoDreamEnabled` (boolean): enable background memory consolidation (auto-dream); overrides server-side default. - `autoCompactEnabled` (boolean): automatically compact conversation when context fills. - `autoCompactWindow` (int; 100,000–1,000,000): auto-compact window size. - `excludeDynamicSections` (boolean): drop per-user dynamic sections (cwd, auto-memory path) from the cached system prompt and re-inject them as the first user message — enables cross-user prompt-cache hits at the cost of slightly less authoritative steering on cwd/memory location. ### Thinking & fast mode - `alwaysThinkingEnabled` (boolean): false disables thinking; absent/true = automatic for supported models. - `fastMode` (boolean): true = fast mode on (Opus 4.6 only). - `fastModePerSessionOptIn` (boolean): if true, fast mode does not persist across sessions; each session starts with it off. ### Sessions, files, attribution - `autoUploadSessions` (boolean): mirror local sessions to claude.ai as view-only (no remote control). - `fileCheckpointingEnabled` (boolean): snapshot files before edits so `/rewind` can restore them. - `attribution` (object): controls Claude's git commit and PR attribution trailers. Shape: `{ "commit": "...", "pr": "..." }`. Empty string hides the trailer. - `includeGitInstructions` (boolean; default true): include built-in commit/PR workflow instructions in the system prompt. Equivalent to `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1`. - `awaySummaryEnabled` (boolean; @internal): false disables the session recap on resume after 5+ min away. Equivalent to `CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0`. ### Hooks, agents, MCP, channels - `disableAllHooks` (boolean): disable all hooks AND statusLine execution. - `disableSkillShellExecution` (boolean): disable inline shell execution in skills and custom slash commands. Commands are replaced with a placeholder. - `disableBackgroundAgents` (boolean): disable the background-agents fleet (`claude agents`, `--bg`, `/background`, the daemon). Equivalent to `CLAUDE_CODE_DISABLE_AGENTS_FLEET=1`. Typically managed. - `disableRemoteControl` (boolean): disable Remote Control (`claude.ai/code`, `claude remote-control`, `--remote-control`/`--rc`, auto-start, in-session toggle). Typically managed. - `enableAllProjectMcpServers` (boolean): auto-approve all MCP servers in the project. - `channelsEnabled` (boolean): managed-org opt-in for MCP `claude/channel` notifications (Teams/Enterprise default off; Console default on unless managed settings exist). ### Sandbox & permissions - `dangerouslyDisableSandbox` (boolean): override sandbox mode (used per-Bash call rather than globally; here for completeness). - `allowUnsandboxedCommands` (boolean; default true): if false, the `dangerouslyDisableSandbox` parameter is ignored; all commands must run sandboxed. - `allowAllUnixSockets` (boolean): allow all Unix sockets (disables blocking on both platforms). ### Managed-only (admin lockdown) Set in managed settings (`/Library/Application Support/ClaudeCode/managed-settings.json` on macOS, `/etc/claude-code/managed-settings.json` on Linux, registry-equivalent on Windows). When true, only managed sources are honored: - `allowManagedDomainsOnly` — only managed `allowedDomains` and `WebFetch(domain:...)` allow rules apply (denies still merge from all sources). - `allowManagedHooksOnly` — only managed hooks run. - `allowManagedMcpServersOnly` — `allowedMcpServers` only from managed; deny still merges. - `allowManagedPermissionRulesOnly` — only managed allow/deny/ask permission rules apply. - `allowManagedReadPathsOnly` — only managed read-path allowlists apply. - `forceRemoteSettingsRefresh` — block startup until remote managed settings are freshly fetched; exit on fetch failure. ### Authentication, model overrides, telemetry - `apiKeyHelper` (string): path to a script that outputs authentication values. - `advisorModel` (string): advisor model for the server-side advisor tool. - `appendSubagentSystemPrompt` (string; @internal): additional system prompt appended to every Task-tool subagent. Gated by `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT=1`. - `model` (string): default model override (alias like `sonnet`/`opus`/`haiku`, or full ID like `claude-opus-4-7`). - `feedbackSurveyRate` (number; 0–1): probability the session quality survey appears when eligible (0.05 is a reasonable starting point). - `otelHeadersHelper` (string): path to a script that outputs OpenTelemetry headers (paired with the `OTEL_*` env vars above). ### Plugins / marketplaces - `autoUpdate` (boolean; per-marketplace entry): auto-update this marketplace and its installed plugins on startup. - `forceRemoveDeletedPlugins` (boolean): plugins removed from a marketplace are auto-uninstalled and flagged for users. ### Platform-specific - `wslInheritsWindowsSettings` (boolean; Windows admin source only): whether WSL Claude Code inherits the Windows-side admin settings. ## References - Settings: https://docs.anthropic.com/en/docs/claude-code/settings - Settings files: https://docs.anthropic.com/en/docs/claude-code/settings#settings-files - Environment variables: https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables ## Related - [[Claude Code]] - [[Claude Code Permissions]] - [[Claude Code Memory]]