Environment variables
Complete reference for environment variables that control Claude Code behavior.
Claude Code supports the following environment variables to control its behavior. Set them in your shell before launching claude, or configure them in settings.json under the env key to apply them to every session or roll them out across your team.
| Variable | Purpose |
|---|---|
ANTHROPIC_API_KEY | API key sent as X-Api-Key header. When set, this key is used instead of your Claude Pro, Max, Team, or Enterprise subscription even if you are logged in. In non-interactive mode (-p), the key is always used when present. In interactive mode, you are prompted to approve the key once before it overrides your subscription. To use your subscription instead, run unset ANTHROPIC_API_KEY |
ANTHROPIC_AUTH_TOKEN | Custom value for the Authorization header (the value you set here will be prefixed with Bearer ) |
ANTHROPIC_BASE_URL | Override the API endpoint to route requests through a proxy or gateway. When set to a non-first-party host, MCP tool search is disabled by default. Set ENABLE_TOOL_SEARCH=true if your proxy forwards tool_reference blocks |
ANTHROPIC_CUSTOM_HEADERS | Custom headers to add to requests (Name: Value format, newline-separated for multiple headers) |
ANTHROPIC_CUSTOM_MODEL_OPTION | Model ID to add as a custom entry in the /model picker. Use this to make a non-standard or gateway-specific model selectable without replacing built-in aliases. See Model configuration |
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_CUSTOM_MODEL_OPTION_NAME | Display name for the custom model entry in the /model picker. Defaults to the model ID when not set |
ANTHROPIC_DEFAULT_HAIKU_MODEL | See Model configuration |
ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION | See Model configuration |
ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME | See Model configuration |
ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES | See Model configuration |
ANTHROPIC_DEFAULT_OPUS_MODEL | See Model configuration |
ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION | See Model configuration |
ANTHROPIC_DEFAULT_OPUS_MODEL_NAME | See Model configuration |
ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES | See Model configuration |
ANTHROPIC_DEFAULT_SONNET_MODEL | See Model configuration |
ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION | See Model configuration |
ANTHROPIC_DEFAULT_SONNET_MODEL_NAME | See Model configuration |
ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES | See Model configuration |
ANTHROPIC_FOUNDRY_API_KEY | API key for Microsoft Foundry authentication (see Microsoft Foundry) |
ANTHROPIC_FOUNDRY_BASE_URL | Full base URL for the Foundry resource (for example, https://my-resource.services.ai.azure.com/anthropic). Alternative to ANTHROPIC_FOUNDRY_RESOURCE (see Microsoft Foundry) |
ANTHROPIC_FOUNDRY_RESOURCE | Foundry resource name (for example, my-resource). Required if ANTHROPIC_FOUNDRY_BASE_URL is not set (see Microsoft Foundry) |
ANTHROPIC_MODEL | Name of the model setting to use (see Model Configuration) |
ANTHROPIC_SMALL_FAST_MODEL | [DEPRECATED] Name of Haiku-class model for background tasks |
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION | Override AWS region for the Haiku-class model when using Bedrock |
AWS_BEARER_TOKEN_BEDROCK | Bedrock API key for authentication (see Bedrock API keys) |
BASH_DEFAULT_TIMEOUT_MS | Default timeout for long-running bash commands |
BASH_MAX_OUTPUT_LENGTH | Maximum number of characters in bash outputs before they are middle-truncated |
BASH_MAX_TIMEOUT_MS | Maximum timeout the model can set for long-running bash commands |
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 shell spawned by Claude Code |
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | Set the percentage of context capacity (1-100) at which auto-compaction triggers. By default, auto-compaction triggers at approximately 95% capacity. Use lower values like 50 to compact earlier. Values above the default threshold have no effect. Applies to both main conversations and subagents. This percentage aligns with the context_window.used_percentage field available in status line |
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR | Return to the original working directory after each Bash command |
CLAUDE_CODE_ACCOUNT_UUID | Account UUID for the authenticated user. Used by SDK callers to provide account information synchronously, avoiding a race condition where early telemetry events lack account metadata. Requires CLAUDE_CODE_USER_EMAIL and CLAUDE_CODE_ORGANIZATION_UUID to also be set |
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD | Set to 1 to load CLAUDE.md files from directories specified with --add-dir. By default, additional directories do not load memory files |
CLAUDE_CODE_AUTO_COMPACT_WINDOW | Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for extended context models. Use a lower value like 500000 on a 1M model to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's used_percentage, which always uses the model's full context window |
CLAUDE_CODE_API_KEY_HELPER_TTL_MS | Interval in milliseconds at which credentials should be refreshed (when using apiKeyHelper) |
CLAUDE_CODE_CLIENT_CERT | Path to client certificate file for mTLS authentication |
CLAUDE_CODE_CLIENT_KEY | Path to client private key file for mTLS authentication |
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE | Passphrase for encrypted CLAUDE_CODE_CLIENT_KEY (optional) |
CLAUDE_CODE_DISABLE_1M_CONTEXT | Set to 1 to disable 1M context window support. When set, 1M model variants are unavailable in the model picker. Useful for enterprise environments with compliance requirements |
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING | Set to 1 to disable adaptive reasoning for Opus 4.6 and Sonnet 4.6. When disabled, these models fall back to the fixed thinking budget controlled by MAX_THINKING_TOKENS |
CLAUDE_CODE_DISABLE_AUTO_MEMORY | Set to 1 to disable auto memory. Set to 0 to force auto memory on during the gradual rollout. When disabled, Claude does not create or load auto memory files |
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS | Set to 1 to remove built-in commit and PR workflow instructions and the git status snapshot from Claude's system prompt. Useful when using your own git workflow skills. Takes precedence over the includeGitInstructions setting when set |
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS | Set to 1 to disable all background task functionality, including the run_in_background parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut |
CLAUDE_CODE_DISABLE_CRON | Set to 1 to disable scheduled tasks. The /loop skill and cron tools become unavailable and any already-scheduled tasks stop firing, including tasks that are already running mid-session |
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS | Set to 1 to strip Anthropic-specific anthropic-beta request headers and beta tool-schema fields (such as defer_loading and eager_input_streaming) from API requests. Use this when a proxy gateway rejects requests with errors like "Unexpected value(s) for the anthropic-beta header" or "Extra inputs are not permitted". Standard fields (name, description, input_schema, cache_control) are preserved. |
CLAUDE_CODE_DISABLE_FAST_MODE | Set to 1 to disable fast mode |
CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY | Set to 1 to disable the "How is Claude doing?" session quality surveys. Surveys are also disabled when DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set. See Session quality surveys |
CLAUDE_CODE_DISABLE_MOUSE | Set to 1 to disable mouse tracking in fullscreen rendering. Keyboard scrolling with PgUp and PgDn still works. Use this to keep your terminal's native copy-on-select behavior |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | Equivalent of setting DISABLE_AUTOUPDATER, DISABLE_FEEDBACK_COMMAND, DISABLE_ERROR_REPORTING, and DISABLE_TELEMETRY |
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 |
CLAUDE_CODE_DISABLE_TERMINAL_TITLE | Set to 1 to disable automatic terminal title updates based on conversation context |
CLAUDE_CODE_EFFORT_LEVEL | Set the effort level for supported models. Values: low, medium, high, max (Opus 4.6 only), or auto to use the model default. Takes precedence over /effort and the effortLevel setting. See Adjust effort level |
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION | Set to false to disable prompt suggestions (the "Prompt suggestions" toggle in /config). These are the grayed-out predictions that appear in your prompt input after Claude responds. See Prompt suggestions |
CLAUDE_CODE_ENABLE_TASKS | Set to true to enable the task tracking system in non-interactive mode (the -p flag). Tasks are on by default in interactive mode. See Task list |
CLAUDE_CODE_ENABLE_TELEMETRY | Set to 1 to enable OpenTelemetry data collection for metrics and logging. Required before configuring OTel exporters. See Monitoring |
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY | Time in milliseconds to wait after the query loop becomes idle before automatically exiting. Useful for automated workflows and scripts using SDK mode |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS | Set to 1 to enable agent teams. Agent teams are experimental and disabled by default |
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS | Override the default token limit for file reads. Useful when you need to read larger files in full |
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL | Skip auto-installation of IDE extensions. Equivalent to setting autoInstallIdeExtension to false |
CLAUDE_CODE_MAX_OUTPUT_TOKENS | Set the maximum number of output tokens for most requests. Defaults and caps vary by model; see max output tokens. Increasing this value reduces the effective context window available before auto-compaction triggers. |
CLAUDE_CODE_NEW_INIT | Set to true to make /init run an interactive setup flow. The flow asks which files to generate, including CLAUDE.md, skills, and hooks, before exploring the codebase and writing them. Without this variable, /init generates a CLAUDE.md automatically without prompting. |
CLAUDE_CODE_NO_FLICKER | Set to 1 to enable fullscreen rendering, a research preview that reduces flicker and keeps memory flat in long conversations |
CLAUDE_CODE_ORGANIZATION_UUID | Organization UUID for the authenticated user. Used by SDK callers to provide account information synchronously. Requires CLAUDE_CODE_ACCOUNT_UUID and CLAUDE_CODE_USER_EMAIL to also be set |
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See Dynamic headers |
CLAUDE_CODE_PLAN_MODE_REQUIRED | Auto-set to true on agent team teammates that require plan approval. Read-only: set by Claude Code when spawning teammates. See require plan approval |
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS | Timeout in milliseconds for git operations when installing or updating plugins (default: 120000). Increase this value for large repositories or slow network connections. See Git operations time out |
CLAUDE_CODE_PLUGIN_SEED_DIR | Path to one or more read-only plugin seed directories, separated by : on Unix or ; on Windows. Use this to bundle a pre-populated plugins directory into a container image. Claude Code registers marketplaces from these directories at startup and uses pre-cached plugins without re-cloning. See Pre-populate plugins for containers |
CLAUDE_CODE_PROXY_RESOLVES_HOSTS | Set to true to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution |
CLAUDE_CODE_SCROLL_SPEED | Set the mouse wheel scroll multiplier in fullscreen rendering. Accepts values from 1 to 20. Set to 3 to match vim if your terminal sends one wheel event per notch without amplification |
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS | Maximum time in milliseconds for SessionEnd hooks to complete (default: 1500). Applies to session exit, /clear, and switching sessions via interactive /resume. Per-hook timeout values are also capped by this budget |
CLAUDE_CODE_SHELL | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, bash vs zsh) |
CLAUDE_CODE_SHELL_PREFIX | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: /path/to/logger.sh will execute /path/to/logger.sh <command> |
CLAUDE_CODE_SIMPLE | Set to 1 to run with a minimal system prompt and only the Bash, file read, and file edit tools. MCP tools from --mcp-config are still available. Disables auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. The --bare CLI flag sets this |
CLAUDE_CODE_SKIP_BEDROCK_AUTH | Skip AWS authentication for Bedrock (for example, when using an LLM gateway) |
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. The API still enforces organization-level disable separately |
CLAUDE_CODE_SKIP_FOUNDRY_AUTH | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |
CLAUDE_CODE_SKIP_VERTEX_AUTH | Skip Google authentication for Vertex (for example, when using an LLM gateway) |
CLAUDE_CODE_SUBAGENT_MODEL | See Model configuration |
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB | Set to 1 to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers). The parent Claude process keeps these credentials for API calls, but child processes cannot read them, reducing exposure to prompt injection attacks that attempt to exfiltrate secrets via shell expansion. claude-code-action sets this automatically when allowed_non_write_users is configured |
CLAUDE_CODE_TASK_LIST_ID | Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list. See Task list |
CLAUDE_CODE_TEAM_NAME | Name of the agent team this teammate belongs to. Set automatically on agent team members |
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 |
CLAUDE_CODE_USER_EMAIL | Email address for the authenticated user. Used by SDK callers to provide account information synchronously. Requires CLAUDE_CODE_ACCOUNT_UUID and CLAUDE_CODE_ORGANIZATION_UUID to also be set |
CLAUDE_CODE_USE_BEDROCK | Use Bedrock |
CLAUDE_CODE_USE_FOUNDRY | Use Microsoft Foundry |
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. See PowerShell tool |
CLAUDE_CODE_USE_VERTEX | Use Vertex |
CLAUDE_CONFIG_DIR | Customize where Claude Code stores its configuration and data files |
CLAUDE_ENV_FILE | Path to a shell script that Claude Code sources before each Bash command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by SessionStart, CwdChanged, and FileChanged hooks |
CLAUDE_STREAM_IDLE_TIMEOUT_MS | Timeout in milliseconds before the streaming idle watchdog closes a stalled connection. Default: 90000 (90 seconds). Increase this value if long-running tools or slow networks cause premature timeout errors |
DISABLE_AUTOUPDATER | Set to 1 to disable automatic updates. |
DISABLE_COST_WARNINGS | Set to 1 to disable cost warning messages |
DISABLE_ERROR_REPORTING | Set to 1 to opt out of Sentry error reporting |
DISABLE_FEEDBACK_COMMAND | Set to 1 to disable the /feedback command. The older name DISABLE_BUG_COMMAND is also accepted |
DISABLE_INSTALLATION_CHECKS | Set to 1 to disable installation warnings. Use only when manually managing the installation location, as this can mask issues with standard installations |
DISABLE_PROMPT_CACHING | Set to 1 to disable prompt caching for all models (takes precedence over per-model settings) |
DISABLE_PROMPT_CACHING_HAIKU | Set to 1 to disable prompt caching for Haiku models |
DISABLE_PROMPT_CACHING_OPUS | Set to 1 to disable prompt caching for Opus models |
DISABLE_PROMPT_CACHING_SONNET | Set to 1 to disable prompt caching for Sonnet models |
DISABLE_TELEMETRY | Set to 1 to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |
ENABLE_CLAUDEAI_MCP_SERVERS | Set to false to disable claude.ai MCP servers in Claude Code. Enabled by default for logged-in users |
ENABLE_TOOL_SEARCH | Controls MCP tool search. Unset: all MCP tools deferred by default, but loaded upfront when ANTHROPIC_BASE_URL points to a non-first-party host. Values: true (always defer including proxies), auto (threshold mode: load upfront if tools fit within 10% of context), auto:N (custom threshold, e.g., auto:5 for 5%), false (load all upfront) |
FORCE_AUTOUPDATE_PLUGINS | Set to true to force plugin auto-updates even when the main auto-updater is disabled via DISABLE_AUTOUPDATER |
HTTP_PROXY | Specify HTTP proxy server for network connections |
HTTPS_PROXY | Specify HTTPS proxy server for network connections |
IS_DEMO | Set to true to enable demo mode: hides email and organization from the UI, skips onboarding, and hides internal commands. Useful for streaming or recording sessions |
MAX_MCP_OUTPUT_TOKENS | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000) |
MAX_THINKING_TOKENS | Override the extended thinking token budget. The ceiling is the model's max output tokens minus one. Set to 0 to disable thinking entirely. On models with adaptive reasoning (Opus 4.6, Sonnet 4.6), the budget is ignored unless adaptive reasoning is disabled via CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING |
MCP_CLIENT_SECRET | OAuth client secret for MCP servers that require pre-configured credentials. Avoids the interactive prompt when adding a server with --client-secret |
MCP_OAUTH_CALLBACK_PORT | Fixed port for the OAuth redirect callback, as an alternative to --callback-port when adding an MCP server with pre-configured credentials |
MCP_TIMEOUT | Timeout in milliseconds for MCP server startup |
MCP_TOOL_TIMEOUT | Timeout in milliseconds for MCP tool execution |
NO_PROXY | List of domains and IPs to which requests will be directly issued, bypassing proxy |
SLASH_COMMAND_TOOL_CHAR_BUDGET | Override the character budget for skill metadata shown to the Skill tool. The budget scales dynamically at 1% of the context window, with a fallback of 8,000 characters. Legacy name kept for backwards compatibility |
USE_BUILTIN_RIPGREP | Set to 0 to use system-installed rg instead of rg included with Claude Code |
VERTEX_REGION_CLAUDE_3_5_HAIKU | Override region for Claude 3.5 Haiku when using Vertex AI |
VERTEX_REGION_CLAUDE_3_7_SONNET | Override region for Claude 3.7 Sonnet when using Vertex AI |
VERTEX_REGION_CLAUDE_4_0_OPUS | Override region for Claude 4.0 Opus when using Vertex AI |
VERTEX_REGION_CLAUDE_4_0_SONNET | Override region for Claude 4.0 Sonnet when using Vertex AI |
VERTEX_REGION_CLAUDE_4_1_OPUS | Override region for Claude 4.1 Opus when using Vertex AI |
See also
- Settings: configure environment variables in
settings.jsonso they apply to every session - CLI reference: launch-time flags
- Network configuration: proxy and TLS setup