guide12 min read2mo ago

Claude Code Environment Variables in 2026: Full Reference

The official reference lists 363 of them. The guides that rank for this cover eight to twenty-eight. Here is how Claude Code actually reads an environment variable, and the four ways yours is accepted and then ignored.

Claude Code Environment Variables in 2026: Full Reference
claude codeclaude code environment variablesenvironment variablessettings.jsonCLAUDE_CODE_claude code configuration

Key Takeaways
  • The official reference table carries 363 named variables. The four guides currently ranking for this document between 8 and 28 of them.
  • Opting out of telemetry also stops feature-flag fetching, which silently removes AGENTS.md support, Remote Control, claude.ai skill and plugin sync, /import and /skill-doctor.
  • Project and local settings are not allowed to set about fifteen variables. Claude Code drops each one and logs a warning you only see with claude --debug.
  • Precedence is decided per variable, not by one ladder. ANTHROPIC_MODEL beats the model setting; --model beats them both.
  • Three off switches ignore the value entirely: setting DISABLE_TELEMETRY=0 still opts you out. Only unsetting the variable turns it back on.

363 variables · 4 silent-ignore classes · 15 the repo cannot set · every value quoted from the reference

You set CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=none to lift the subagent cap, restarted, and got the same cap. Nothing errored. The variable is spelled correctly, it is in the reference, and Claude Code read it and threw the value away, because that variable accepts plain digits and ignores anything else.

That is the recurring shape here, and it is worth naming before the table: a Claude Code environment variable that does nothing usually looks exactly like one that worked. Bad values are discarded rather than rejected, a settings file can be told to set a variable it is not allowed to set, and two of the most commonly copied off switches ignore the value you give them.

So this is the reference for the mechanics rather than the list: where Claude Code reads variables from, which source wins for a given key, what happens to a value it does not like, and the handful of variables whose side effects reach much further than their names suggest.

Every name, default, accepted value and version number below is checked against Anthropic's environment variables reference and settings reference rather than other write-ups, which matters more than usual on this topic: the most detailed competing guide states the precedence rule backwards, and the next most detailed predates a v2.1.251 change that moved several variables out of a repository's reach.

Five thin violet light beams travelling left to right into a dark vertical panel with five narrow slots in it. Four of the beams stop dead at the panel and only one passes through and carries on to the right edge
Set correctly, spelled correctly, read by Claude Code, and thrown away without a word.

How Many Variables Claude Code Actually Reads

Four statistics side by side: the official reference table names 363 variables, the four guides currently ranking for this query document between 8 and 28 of them each, 15 variables cannot be set by project or local settings at all, and there are 4 classes of value that Claude Code accepts and then silently ignores
The gap is not obscure variables. It is the three behaviours that actually cost people time.

Counting the rows in the official table gives 363 distinct variable names. That number is the reason most guides on this topic feel thin rather than wrong: they pick a plausible two dozen and present them as the set.

FamilyCountWhat it controls
---------
CLAUDE_CODE_ and other CLAUDE_223Behaviour, limits, tool availability, transport, session plumbing
ANTHROPIC_*46Auth, base URLs, model aliases, beta headers, org and workspace IDs
DISABLE_*22Blunt off switches for updates, compaction, caching, telemetry, commands
VERTEX_REGION_CLAUDE_*17Per-model region pinning on Google Cloud's Agent Platform
MCP_*14MCP startup, timeouts, discovery cache, OAuth callback port
OTEL_*12What OpenTelemetry metrics and logs include
BASH_, MAX_, API_*8Bash and API timeouts, output caps, thinking budget
Proxy and singletons21HTTP_PROXY, NO_PROXY, DO_NOT_TRACK, ENABLE_TOOL_SEARCH and similar

You do not need 363 of them. The practical set is closer to fifteen, and the last section names the ones I actually set. The count matters for a different reason: if a behaviour annoys you, there is probably a variable for it, and the reason you have not found it is that no third-party list is complete.

The Two Places to Set One, and What Changes Between Them

The Claude Code documentation page titled Environment variables, the official reference this article quotes every variable name, default, accepted value and version number from
The reference table itself. Every figure on this page is built from it, not from secondary guides.

A variable in your shell lasts for that terminal session. A variable under the env key in a settings.json file applies every time claude runs, however it was launched. Those two sentences are where most guides stop, and the differences underneath them are the part that bites.

BehaviourShell exportenv key in settings
---------
When it is readAt startup onlyAt startup, and again when a saved change alters the merged env
Conflict with the other sourceLosesWins, by being written into the process environment
Removing itTakes effect next launchDoes not unset it in a running session
Unsetting a variableunset VARImpossible; set "" instead
Reaches subprocessesYesYes, including the empty string

Two of those rows are worth expanding. You cannot remove a variable from a settings file, only assign to it, so to defeat a stale CLAUDE_CODE_USE_VERTEX exported by a shell profile you do not control, set "CLAUDE_CODE_USE_VERTEX": "" in your env block. Claude Code treats the empty value as unset for provider selection, though subprocesses still inherit an empty variable.

And the live-reload is not universal. Features that read their variables once at startup, such as OpenTelemetry monitoring and CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS, keep their startup values until you relaunch, no matter how many times you save the file.

When the setting arrives from project or local settings rather than your own, there is a further gate: those values apply after you trust the workspace, or at startup in -p mode, which never shows the trust dialog. The same workspace-trust question governs Claude Code's permission rules, and it is worth knowing that a cloned repository's env block sits behind it.

Precedence Is Per Variable, Not One Ladder

Table of seven variables against what each one beats and what beats it. ANTHROPIC MODEL beats the model setting but loses to the model flag and slash command. CLAUDE CODE AUTO CONNECT IDE beats the autoConnectIde setting and loses to nothing. CLAUDE CODE EFFORT LEVEL beats the effort flag, the effort slash command and the effortLevel setting, and loses only to the maxEffortLevel cap. CLAUDE CODE MAX TURNS beats nothing and loses to the max-turns flag. BASH MAX OUTPUT LENGTH loses to the bashOutputMaxChars setting
The CLI flag does not always win. Check the row for the pair you are setting.

Every competing guide on this topic presents a numbered priority ladder. The official page does not, and says why: which source Claude Code reads first "differs per key". The one detailed guide that commits to a ladder gets the direction wrong, telling readers that settings.json values override environment variables when an equivalent key exists.

For ANTHROPIC_MODEL that is backwards. Claude Code reads the variable first and falls back to the model setting only when the variable is unset.

VariableBeatsIs beaten by
---------
ANTHROPIC_MODELthe model setting--model, /model
CLAUDE_CODE_AUTO_CONNECT_IDEthe autoConnectIde settingnothing
CLAUDE_CODE_EFFORT_LEVEL--effort, /effort, effortLevelthe maxEffortLevel cap
CLAUDE_CODE_MAX_TURNSnothing--max-turns
CLAUDE_CODE_DISABLE_AUTO_MEMORYautoMemoryEnabled, in either directionnothing
BASH_MAX_OUTPUT_LENGTHnothingthe bashOutputMaxChars setting
CLAUDE_CODE_PROMPT_CACHE_TTLpromptCacheTtl, ENABLE_PROMPT_CACHING_1HFORCE_PROMPT_CACHING_5M

Notice that the CLI flag does not always win either. CLAUDE_CODE_EFFORT_LEVEL overrides both --effort and an in-session /effort, which is the opposite of the --model case one row above it. Between settings files, env values do follow ordinary settings precedence, so a managed entry beats the same variable in user or project settings.

The honest summary is that there is no rule to memorise. Check the row for the pair you are setting, and if the two guides you found disagree, believe the one that names a version number.

The Variables a Repository Is Not Allowed to Set

Four groups of variables that project and local settings cannot set: the ones deciding where Claude Code writes its own files, the three that export session content including OTEL LOG RAW API BODIES and BETA TRACING ENDPOINT, the group controlling how Claude Code starts or syncs skills and plugins, and a shorter list ignored from every settings file including yours because Claude Code owns those values
Claude Code drops each one and logs a warning you can only see by running claude with the debug flag.

This is the finding I would most want in front of a team, and none of the four ranking guides mentions it. Project and local settings cannot set variables that a checked-out repository should not control. Claude Code drops each one and logs a warning you can only see with claude --debug.

GroupVariables dropped from project and local settings
------
Where Claude Code writes its own filesCLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, HOME, TMPDIR, TMP, TEMP, the XDG_* family
Variables that export session contentOTEL_LOG_RAW_API_BODIES, ENABLE_BETA_TRACING_DETAILED, BETA_TRACING_ENDPOINT
How Claude Code starts or syncsCLAUDE_CODE_PROCESS_WRAPPER, CLAUDE_CODE_SYNC_SKILLS, CLAUDE_CODE_SYNC_PLUGINS, CLAUDE_CODE_PLUGIN_CACHE_DIR, CLAUDE_CODE_PLUGIN_SEED_DIR

Read that second group again. Before v2.1.251, a .claude/settings.json committed to a repository could set OTEL_LOG_RAW_API_BODIES and BETA_TRACING_ENDPOINT together, which is a checked-in file pointing your raw API bodies at a host of its choosing. It could also set CLAUDE_CONFIG_DIR. Only HOME, XDG_CONFIG_HOME and the start-and-sync group were blocked before that release.

A second, shorter list is ignored from every settings file, yours included, because Claude Code owns those values: CLAUDE_CODE_REMOTE and CLAUDE_CODE_ACCOUNT_UUID, the messaging pair CLAUDE_CODE_MESSAGING_SOCKET (v2.1.224 or later) and CLAUDE_CODE_MESSAGING_TOKEN (v2.1.228 or later), CLAUDE_CODE_PROJECT_DIR_NAME (v2.1.234 or later), and CLAUDE_CODE_RESTRICTED (v2.1.248 or later). Those four read from the launch environment only.

If you are auditing a repository you did not write, this list is the one to check against its .claude/settings.json, alongside the hooks and MCP entries our security best practices piece covers.

Turning Off Telemetry Turns Off More Than Telemetry

Table of five privacy variables against whether each stops telemetry events and whether it stops feature-flag fetching. DISABLE GROWTHBOOK stops only the fetching. DISABLE TELEMETRY, DO NOT TRACK set to 1 and CLAUDE CODE DISABLE NONESSENTIAL TRAFFIC stop both. DISABLE ERROR REPORTING stops telemetry events but leaves flag fetching alone, and a panel lists what breaks when fetching is off, including AGENTS.md support, Remote Control and claude.ai skill and plugin sync
Three of the four are what a privacy-conscious engineer sets on day one. Only the fifth is safe.

Claude Code enables some features through flags it fetches from Anthropic at startup. Four variables stop that fetch, and three of them are the ones a privacy-conscious engineer sets on day one without reading further.

VariableStops telemetry eventsStops feature-flag fetching
---------
DISABLE_GROWTHBOOKNoYes
DISABLE_TELEMETRYYesYes
DO_NOT_TRACK=1YesYes
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICYesYes

Sessions on a third-party provider such as Amazon Bedrock or Google Cloud's Agent Platform skip the fetch too, unless the host platform sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST.

With fetching off, these stop working: reading AGENTS.md files as project instructions, so only CLAUDE.md loads; starting sessions in auto mode by default on Pro, Max and Team plans; Remote Control; messaging sessions on other machines, though same-machine messaging still works; claude import and /import; /skill-doctor and its report in the /plugin Stats tab; syncing the skills and plugins enabled for your claude.ai account into your terminal; the advisor tool; and reading or replying to comments on an artifact.

Two more are quieter still. Claude Code normally excludes MCP tools whose input schema the API would reject; with fetching off it sends the schema anyway and the request fails with a 400 naming the tool by its position. And on Windows with Git Bash installed, claude.ai and Console accounts lose the PowerShell tool by default unless you set CLAUDE_CODE_USE_POWERSHELL_TOOL=1.

If you need the privacy without the collateral damage, DISABLE_ERROR_REPORTING is the safe one. It opts you out of error reporting and does not touch flag fetching. Telemetry events, for what it is worth, do not include code, file paths or bash commands.

One related trap worth knowing before you file a bug: in your first session after an install or an upgrade that adds a feature, a flag-gated feature can simply be missing, and the session can start in Manual mode on a plan that normally starts in auto. Claude Code fetches the flags during that session, so it is there the next time.

Configure the tools before you configure the variables
Most of these variables exist to shape what agents, skills and MCP servers are allowed to do. Skiln indexes installable Claude agents, skills, commands and MCP servers with their real install paths and the tools each one expects, so you can see what you are tuning. Browse agents · Browse skills · Generate a config
Disclosure: Skiln publishes this article and runs the directory it links to.

Off Switches That Do Not Read as Booleans

Three variables ignore their value entirely. Setting them to 0 or false, which is what you would write to turn a feature back on, still turns it off.

  • DISABLE_TELEMETRY
  • DISABLE_ERROR_REPORTING
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

Any non-empty value opts you out, including the two that look like refusals. The only way back is to remove the variable, which is awkward in a settings file, where the empty string is your only eraser.

The two neighbours behave normally, which is exactly why this is easy to get wrong. DO_NOT_TRACK is read as a standard boolean, so DO_NOT_TRACK=0 leaves telemetry on. DISABLE_GROWTHBOOK=0 likewise leaves flag fetching on. Four variables in the same paragraph of the same reference, and two of them invert.

Values Claude Code Ignores Instead of Rejecting

Back to the opening example. Most numeric variables silently discard a value they cannot parse and carry on with the default, which means a typo produces a working session with the setting you were trying to change still in place.

VariableBad value does whatDefault
---------
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSIgnored; plain digits only, so the cap can be adjusted but never disabled20
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONIgnored; can be raised, not turned off200
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS0, a decimal or any other spelling keeps the default900000
CLAUDE_CODE_SHELLFalls back to auto-detection if not a working bash or zsh pathauto
CLAUDE_CODE_GIT_BASH_PATHIgnored, warning only under --debug; before v2.1.219 it exited at startupauto
CLAUDE_CODE_MAX_OUTPUT_TOKENSValues above the model's cap are lowered to the cap32000 for unknown model IDs
MCP_TOOL_TIMEOUTEnv values under 1000 are floored to one second100000000
CLAUDE_CODE_MAX_TURNSRejected at startup with an errornone

That last row is the exception that proves the pattern is a choice rather than an oversight. A non-positive-integer CLAUDE_CODE_MAX_TURNS stops the session with an error instead of being quietly dropped.

API_TIMEOUT_MS deserves its own warning. Its documented maximum is 2147483647, and a value above that overflows the underlying timer so requests fail immediately rather than late, which reads like a network fault.

The practical habit: after setting a numeric variable, confirm the behaviour changed rather than confirming the variable is exported. echo $VAR proves nothing about whether Claude Code kept it.

Settings Keys That Make a Variable Irrelevant

The Claude Code documentation page titled All settings, a complete reference for every settings key, where each one goes, its type and default, with a filterable index of every key
The settings side of the same question, and where the equivalent keys are documented.

A smaller trap, and the reverse of the precedence table. Some settings.json keys do not override their matching variable, they make Claude Code ignore it outright.

If you set this keyClaude Code ignores
------
bashOutputMaxCharsBASH_MAX_OUTPUT_LENGTH
taskOutputMaxCharsTASK_MAX_OUTPUT_LENGTH

There is a third pattern too, in the "whichever turns it off wins" direction. CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING and the fileCheckpointingEnabled setting both control checkpointing: whichever of the two turns it off, the other cannot turn it back on. So a team-wide fileCheckpointingEnabled: false cannot be defeated by a personal variable, and vice versa.

The Ones I Actually Set

Fifteen variables cover most of what people want from the other 348.

VariableValueWhy
---------
BASH_DEFAULT_TIMEOUT_MS300000The 120000 default kills slow test suites mid-run
BASH_MAX_OUTPUT_LENGTH150000The documented maximum; 30000 truncates real build logs
MCP_TIMEOUT60000Cold MCP servers regularly miss the 30000 startup window
MAX_MCP_OUTPUT_TOKENS50000The 25000 default clips large tool responses
CLAUDE_CODE_MAX_RETRIESleave itCapped at 15 since v2.1.186; use CLAUDE_CODE_RETRY_WATCHDOG for long outages
CLAUDE_CODE_SUBAGENT_MODELhaikuCheap delegation, with CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 to make it stick
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB1Strips credentials from Bash, hook and MCP subprocesses
CLAUDE_CONFIG_DIRper accountalias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'
DISABLE_ERROR_REPORTING1The privacy opt-out that does not break flag-gated features
CLAUDE_ENV_FILEa pathRuns before each Bash command, so virtualenv activation persists
CLAUDE_CODE_DISABLE_FAST_MODE1When predictable pricing matters more than latency
DISABLE_AUTO_COMPACT1If you would rather run /compact yourself

CLAUDE_CODE_SUBPROCESS_ENV_SCRUB is the one I would argue for hardest. It keeps Anthropic and cloud credentials in the parent process and out of every child, which closes the shell-expansion route a prompt injection would use to exfiltrate them. On Linux it also runs Bash subprocesses in an isolated PID namespace, with the side effect that ps, pgrep and kill can no longer see host processes.

Two more are worth knowing without setting: CLAUDE_CODE_SAFE_MODE=1 starts a session with no CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands, agents or output styles loaded, which is the fastest way to find out whether your configuration is the problem. And CLAUDECODE=1 is set in every subprocess Claude Code spawns, so a script can detect that it is running under an agent rather than a human. The subagent configuration reference covers how the model and concurrency variables interact with a .claude/agents file, which is where most of the delegation cost actually gets decided.

Every name, default, accepted value and version number above comes from Anthropic's environment variables reference, the settings reference and the monitoring guide. Where another write-up disagrees with a value here, check its date and whether it names a version: this list grew by dozens of entries over 2026, and the precedence rules changed under several of them.

Frequently Asked Questions

How many environment variables does Claude Code have?▾
The official environment variables reference lists 363 named variables as of September 2026. Roughly 223 are CLAUDE_ or CLAUDE_CODE_ prefixed, 46 are ANTHROPIC_, 22 are DISABLE_, 17 pin per-model Vertex regions, 14 configure MCP and 12 configure OpenTelemetry. Most third-party lists cover 8 to 28 of them.
Does settings.json override an environment variable, or the other way round?▾
It depends on the key, which is why one priority ladder cannot cover it. For ANTHROPIC_MODEL and CLAUDE_CODE_AUTO_CONNECT_IDE Claude Code reads the variable first and uses the setting only when the variable is unset. For BASH_MAX_OUTPUT_LENGTH the opposite holds: setting bashOutputMaxChars makes Claude Code ignore the variable entirely. Check the variable's row in the reference for the pair you are setting.
Why did my environment variable have no effect?▾
Three common causes. The value may have been discarded: most numeric variables accept plain digits only and silently keep the default otherwise. A settings file env block may be overwriting your shell export, since the file value wins. Or the variable may be one that project and local settings are not allowed to set, in which case Claude Code drops it and logs a warning you only see by running claude --debug.
Does disabling telemetry break anything in Claude Code?▾
Yes, and this is the least documented side effect on the topic. DISABLE_TELEMETRY, DO_NOT_TRACK and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC also stop feature-flag fetching, which removes AGENTS.md support, Remote Control, claude.ai skill and plugin sync, claude import, /skill-doctor, the advisor tool and artifact comments. Use DISABLE_ERROR_REPORTING if you want the privacy without the loss.
Why does setting DISABLE_TELEMETRY=0 still disable telemetry?▾
Because that variable ignores its value: any non-empty value opts you out, including 0 and false. The same applies to DISABLE_ERROR_REPORTING and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Unset the variable to turn the behaviour back on. DO_NOT_TRACK and DISABLE_GROWTHBOOK are read as ordinary booleans, so 0 does leave them on.
Can I unset an environment variable from settings.json?▾
Not directly, because a settings file can only assign. Set the variable to an empty string instead, for example "CLAUDE_CODE_USE_VERTEX": "", which Claude Code treats as unset for provider selection. Subprocesses still inherit the empty value. Deleting the line from the file does not unset it in a running session either; that takes a relaunch.
Which variables can a checked-out repository not set?▾
Project and local settings cannot set CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, HOME, TMPDIR, TMP, TEMP or the XDG_ family; OTEL_LOG_RAW_API_BODIES, ENABLE_BETA_TRACING_DETAILED or BETA_TRACING_ENDPOINT; or CLAUDE_CODE_PROCESS_WRAPPER, CLAUDE_CODE_SYNC_SKILLS, CLAUDE_CODE_SYNC_PLUGINS, CLAUDE_CODE_PLUGIN_CACHE_DIR and CLAUDE_CODE_PLUGIN_SEED_DIR. Before v2.1.251 most of that list was allowed.
When do environment variable changes take effect?▾
Shell variables are read at startup, so a change applies the next time you launch claude. Variables under a settings file's env key are reapplied to a running session when the file changes, except for features that read their values once at startup, such as OpenTelemetry monitoring and CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS.

Stay in the Loop

Join 1,000+ developers. Get the best new Skills & MCPs weekly.

No spam. Unsubscribe anytime.