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.

- 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.mdsupport, Remote Control, claude.ai skill and plugin sync,/importand/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_MODELbeats themodelsetting;--modelbeats them both. - Three off switches ignore the value entirely: setting
DISABLE_TELEMETRY=0still 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.

How Many Variables Claude Code Actually Reads

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.
| Family | Count | What it controls |
|---|---|---|
| --- | --- | --- |
CLAUDE_CODE_ and other CLAUDE_ | 223 | Behaviour, limits, tool availability, transport, session plumbing |
ANTHROPIC_* | 46 | Auth, base URLs, model aliases, beta headers, org and workspace IDs |
DISABLE_* | 22 | Blunt off switches for updates, compaction, caching, telemetry, commands |
VERTEX_REGION_CLAUDE_* | 17 | Per-model region pinning on Google Cloud's Agent Platform |
MCP_* | 14 | MCP startup, timeouts, discovery cache, OAuth callback port |
OTEL_* | 12 | What OpenTelemetry metrics and logs include |
BASH_, MAX_, API_* | 8 | Bash and API timeouts, output caps, thinking budget |
| Proxy and singletons | 21 | HTTP_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

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.
| Behaviour | Shell export | env key in settings |
|---|---|---|
| --- | --- | --- |
| When it is read | At startup only | At startup, and again when a saved change alters the merged env |
| Conflict with the other source | Loses | Wins, by being written into the process environment |
| Removing it | Takes effect next launch | Does not unset it in a running session |
| Unsetting a variable | unset VAR | Impossible; set "" instead |
| Reaches subprocesses | Yes | Yes, 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

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.
| Variable | Beats | Is beaten by |
|---|---|---|
| --- | --- | --- |
ANTHROPIC_MODEL | the model setting | --model, /model |
CLAUDE_CODE_AUTO_CONNECT_IDE | the autoConnectIde setting | nothing |
CLAUDE_CODE_EFFORT_LEVEL | --effort, /effort, effortLevel | the maxEffortLevel cap |
CLAUDE_CODE_MAX_TURNS | nothing | --max-turns |
CLAUDE_CODE_DISABLE_AUTO_MEMORY | autoMemoryEnabled, in either direction | nothing |
BASH_MAX_OUTPUT_LENGTH | nothing | the bashOutputMaxChars setting |
CLAUDE_CODE_PROMPT_CACHE_TTL | promptCacheTtl, ENABLE_PROMPT_CACHING_1H | FORCE_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

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.
| Group | Variables dropped from project and local settings |
|---|---|
| --- | --- |
| Where Claude Code writes its own files | CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, HOME, TMPDIR, TMP, TEMP, the XDG_* family |
| Variables that export session content | OTEL_LOG_RAW_API_BODIES, ENABLE_BETA_TRACING_DETAILED, BETA_TRACING_ENDPOINT |
| How Claude Code starts or syncs | CLAUDE_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

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.
| Variable | Stops telemetry events | Stops feature-flag fetching |
|---|---|---|
| --- | --- | --- |
DISABLE_GROWTHBOOK | No | Yes |
DISABLE_TELEMETRY | Yes | Yes |
DO_NOT_TRACK=1 | Yes | Yes |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | Yes | Yes |
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.
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_TELEMETRYDISABLE_ERROR_REPORTINGCLAUDE_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.
| Variable | Bad value does what | Default |
|---|---|---|
| --- | --- | --- |
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS | Ignored; plain digits only, so the cap can be adjusted but never disabled | 20 |
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION | Ignored; can be raised, not turned off | 200 |
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS | 0, a decimal or any other spelling keeps the default | 900000 |
CLAUDE_CODE_SHELL | Falls back to auto-detection if not a working bash or zsh path | auto |
CLAUDE_CODE_GIT_BASH_PATH | Ignored, warning only under --debug; before v2.1.219 it exited at startup | auto |
CLAUDE_CODE_MAX_OUTPUT_TOKENS | Values above the model's cap are lowered to the cap | 32000 for unknown model IDs |
MCP_TOOL_TIMEOUT | Env values under 1000 are floored to one second | 100000000 |
CLAUDE_CODE_MAX_TURNS | Rejected at startup with an error | none |
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

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 key | Claude Code ignores |
|---|---|
| --- | --- |
bashOutputMaxChars | BASH_MAX_OUTPUT_LENGTH |
taskOutputMaxChars | TASK_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.
| Variable | Value | Why |
|---|---|---|
| --- | --- | --- |
BASH_DEFAULT_TIMEOUT_MS | 300000 | The 120000 default kills slow test suites mid-run |
BASH_MAX_OUTPUT_LENGTH | 150000 | The documented maximum; 30000 truncates real build logs |
MCP_TIMEOUT | 60000 | Cold MCP servers regularly miss the 30000 startup window |
MAX_MCP_OUTPUT_TOKENS | 50000 | The 25000 default clips large tool responses |
CLAUDE_CODE_MAX_RETRIES | leave it | Capped at 15 since v2.1.186; use CLAUDE_CODE_RETRY_WATCHDOG for long outages |
CLAUDE_CODE_SUBAGENT_MODEL | haiku | Cheap delegation, with CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 to make it stick |
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB | 1 | Strips credentials from Bash, hook and MCP subprocesses |
CLAUDE_CONFIG_DIR | per account | alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude' |
DISABLE_ERROR_REPORTING | 1 | The privacy opt-out that does not break flag-gated features |
CLAUDE_ENV_FILE | a path | Runs before each Bash command, so virtualenv activation persists |
CLAUDE_CODE_DISABLE_FAST_MODE | 1 | When predictable pricing matters more than latency |
DISABLE_AUTO_COMPACT | 1 | If 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.
Related Articles
- Claude Code Permissions in 2026: The settings.json Guide
- Claude Code Subagents in 2026: The Config Reference
- Claude Code Slash Commands in 2026: The Full Reference
- Claude Code Output Styles in 2026: The Complete Guide
- Claude Code Hooks: Complete Guide with 15 Ready-to-Use Examples
- Claude Code Security Best Practices: Protect Your Codebase from AI Risks
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.
