Environment variables

Environment variables are the lowest-level way to change how Claude Code behaves: which provider and model it talks to, how long it waits, what it logs, which features are switched on. Many of the same knobs also exist as settings, CLI flags or in-session commands, and this page tells you which wins when they disagree.

The reference is grouped by purpose rather than alphabetically, because you are usually trying to solve one problem at a time. Use your browser's find to jump to a specific name.

Setting a variable

In your shell

A shell variable lasts for that terminal session. Set it before launching:

export API_TIMEOUT_MS=900000
claude

$env:API_TIMEOUT_MS = "900000"
claude

set API_TIMEOUT_MS=900000
claude

To make it permanent, add the export to ~/.zshrc or ~/.bashrc; on Windows use [Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "900000", "User") in PowerShell or setx API_TIMEOUT_MS "900000" in CMD, then open a new terminal. Check it with echo $API_TIMEOUT_MS, echo $env:API_TIMEOUT_MS or echo %API_TIMEOUT_MS%.

In a settings file

Put variables under env in a settings file and they apply every time claude runs, however it was launched:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "CLAUDE_CODE_DISABLE_TERMINAL_TITLE": "1"
  }
}

Values are copied literally; no shell expands them, so ~ and $HOME stay as typed. Use absolute paths, e.g. "CLAUDE_CONFIG_DIR": "/Users/cam/.claude-clients".

Which file you choose decides who is affected:

A running session picks up new and changed env values when the file is saved, except for features that read their variables once at start-up (OpenTelemetry, for example). Removing a variable from the file does not unset it in a running session; that happens at next launch. See Settings for file locations and precedence.

Which value wins

• Variable versus setting. It depends on the pair. ANTHROPIC_MODEL and CLAUDE_CODE_AUTO_CONNECT_IDE are read before the model and autoConnectIde settings. Check each variable's entry below and the key's entry in the settings reference.
• Shell versus settings env. In most sessions the settings file wins, because Claude Code writes each env entry into its process environment over the inherited value. A handful of variables are special-cased; the settings reference lists them.
• Removing a shell variable from settings. You cannot unset a variable from a settings file, but an empty string counts as unset for provider selection: "CLAUDE_CODE_USE_VERTEX": "" neutralises a stale export from a profile you do not control. Subprocesses still inherit the empty value.
• Between settings files, normal settings precedence applies, so managed beats user and project. Project and local settings cannot set some variables at all, such as CLAUDE_CONFIG_DIR and the OpenTelemetry exporter variables.
• Versus flags and commands, it varies: --model and /model beat ANTHROPIC_MODEL, but CLAUDE_CODE_EFFORT_LEVEL beats --effort and /effort. Entries below say so where it matters.
• Timing. Shell variables are read at start-up; settings env values are re-applied when the file changes (with the start-up-only exceptions above).

Value formats

• Numbers accept scientific notation and digit separators, so 2e3 means 2000 and 64_000 means 64000, unless an entry says plain digits only. (Before v2.1.211, these spellings could silently produce tiny values.)
• On/off variables accept 1, true, yes, on and 0, false, no, off, in any case.
• Presence-only variables treat any non-empty value, including 0 and false, as on. Unset them (or set them empty) to turn them off. These are CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DISABLE_ERROR_REPORTING, CLAUDE_CODE_TMUX_TRUECOLOR, FALLBACK_FOR_ALL_PRIMARY_MODELS and IS_DEMO.
• FORCE_HYPERLINK is read as a number, so only 0 turns it off.

Warning: The presence-only rule catches people out. DISABLE_TELEMETRY=0 still disables telemetry.

Authentication

Choosing a provider

Amazon Bedrock and Mantle

Google Cloud's Agent Platform

Microsoft Foundry

Claude Platform on AWS

Request shaping for gateways

Models

Thinking, effort, output and context

Prompt caching

Prompt caching explains TTLs and costs.

Network, timeouts and retries

Shell, tools and files

MCP

See MCP for how these interact.

Subagents, background work and workflows

Plugins and skills

Sessions, history and configuration

Interface and accessibility

Switching features off

Updates, telemetry and privacy

OpenTelemetry

Set the variables that switch on export, choose a destination or capture content in your shell, user settings or managed settings; project and local settings ignore them (except their off values). OTEL_RESOURCE_ATTRIBUTES and interval, timeout and compression variables do apply from project settings. Full details are on Monitoring usage.

Security hardening

See Permission modes for what counts as a critical path.

The subprocess credential scrub

With CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1, Bash commands, hooks and stdio MCP servers start without your credentials, which limits what a prompt injection can steal. Claude Code itself keeps them for its own API calls. Detection is by variable name or value shape, so treat it as one layer alongside tight permissions.

Because GitHub tokens survive, give CI jobs the narrowest permissions, and deny them to sandboxed commands via sandbox.credentials if needed (see Sandboxing). On Linux the scrub also isolates Bash in its own PID namespace so it cannot read other processes' environments via /proc, which means ps, pgrep and kill cannot see host processes. claude-code-action turns the scrub on when allowed_non_write_users is set. (Before v2.1.251 it only removed the first two rows.)

Variables Claude Code sets for you

Read these in scripts and hooks; do not set them.

Agent Platform region overrides

Each overrides the Google Cloud region for one model: VERTEX_REGION_CLAUDE_3_5_HAIKU, VERTEX_REGION_CLAUDE_3_5_SONNET, VERTEX_REGION_CLAUDE_3_7_SONNET, VERTEX_REGION_CLAUDE_4_0_OPUS, VERTEX_REGION_CLAUDE_4_0_SONNET, VERTEX_REGION_CLAUDE_4_1_OPUS, VERTEX_REGION_CLAUDE_4_5_OPUS, VERTEX_REGION_CLAUDE_4_5_SONNET, VERTEX_REGION_CLAUDE_4_6_OPUS, VERTEX_REGION_CLAUDE_4_6_SONNET, VERTEX_REGION_CLAUDE_4_7_OPUS, VERTEX_REGION_CLAUDE_4_8_OPUS, VERTEX_REGION_CLAUDE_5_OPUS (v2.1.219), VERTEX_REGION_CLAUDE_5_SONNET (v2.1.197), VERTEX_REGION_CLAUDE_5_5_OPUS (v2.1.280), VERTEX_REGION_CLAUDE_5_5_SONNET (v2.1.284), VERTEX_REGION_CLAUDE_HAIKU_4_5, VERTEX_REGION_CLAUDE_HAIKU_5_5 (v2.1.293), VERTEX_REGION_CLAUDE_FABLE_5 (v2.1.170) and VERTEX_REGION_CLAUDE_FABLE_5_1 (v2.1.257).

Removed variables

CLAUDE_CODE_CONNECT_TIMEOUT_MS (v2.1.186), CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE (v2.1.160), CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE (v2.1.142), CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION (v2.1.224), CLAUDE_SUBAGENT_BG_SHELL_MAX_MS (v2.1.260), TASK_MAX_OUTPUT_LENGTH (v2.1.277) and CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS (v2.1.283) no longer do anything.

Features that need feature-flag fetching

Some features are switched on by flags Claude Code fetches from Anthropic. Fetching is skipped when DISABLE_GROWTHBOOK, DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turn it off; on third-party providers (Bedrock, Claude Platform on AWS, Agent Platform, Foundry) unless the host sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST; and in Claude apps gateway sessions.

Without it you lose:

• /auto-mode-setup.
• Remote Control when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or DISABLE_GROWTHBOOK is set (the telemetry variables have their own rules), and therefore messaging sessions on other machines (same-machine messaging still works).
• claude import and /import.
• /skill-doctor and the /plugin Stats tab.
• Syncing claude.ai skills and plugins into terminal sessions.
• The advisor.
• Reading and replying to artifact comments, and reading other organisations' public artifacts.
• Probing connectors for MCP protocol 2026-07-28, unless MCP_PROTOCOL_NEGOTIATION=auto.
• The PowerShell tool by default on Windows with Git Bash (set CLAUDE_CODE_USE_POWERSHELL_TOOL=1); Windows without Git Bash keeps it.
• Claude-drafted feedback.
• Marking large pastes as pasted rather than typed.
• Excluding MCP tools whose schemas the API would reject (requests including them fail with a 400 naming the tool's position).

The first session after install or upgrade

A flag-gated feature can be missing in your first session after installing or upgrading, and that session may start in a different permission mode. Flags fetched during it are saved, so the next session is normal. Non-interactive first sessions (-p, the SDK, VS Code) may or may not wait for flags before choosing the mode.

Every session behaves like a first session when the environment is wiped each run (CI containers), or when you authenticate with ANTHROPIC_AUTH_TOKEN and no API key against a non-Anthropic ANTHROPIC_BASE_URL, since there is no credential to fetch flags with. Set the starting permission mode explicitly in those setups.

Related

• Settings
• Settings reference
• CLI reference
• Network configuration
• Monitoring usage