How does the env block in a Claude Code settings file interact with shell exports and with variables set in project-level files?
answer
- strings in, subprocesses inherit
- settings beat the inherited shell
- blank it, you can't unset it
- repositories can't redirect files or telemetry
- trust, then live reapply
basics
~20 sIn a terminal session an env value overwrites the same shell export, and between files the highest-precedence one wins. Project and local files can't set some variables, such as CLAUDE_CONFIG_DIR or, since v2.1.282, the telemetry exporter variables.
solid answer
~40 sThe `env` key maps variable names to string values that Claude Code writes into its own environment, so its subprocesses inherit them. In a normal CLI session a settings value replaces the same variable exported in your shell; you can't remove a variable from settings, but `""` cancels it for provider selection. `env` is an ordinary key, so managed beats `--settings`, which beats local, project and user. Project and local files can't set variables that choose where Claude Code writes files, like `CLAUDE_CONFIG_DIR`, and since v2.1.282 they ignore the OpenTelemetry exporter variables except off values. Most project and local `env` values wait until the folder is trusted, edits reapply live, and a removed variable stays set until relaunch.
code
json · 7 lines{
"env": {
"API_TIMEOUT_MS": "1200000",
"BASH_DEFAULT_TIMEOUT_MS": "300000",
"CLAUDE_CODE_USE_VERTEX": ""
}
}go deeper
Recall that the env key sets variables for every session and that values are strings which subprocesses inherit.
Explain settings-over-shell, blanking with an empty string, precedence between files, and which variables project and local files can't set.
Show you know when values apply — trust, -p, live reapply, removal on relaunch — and why a repository may not redirect file storage or telemetry.
Decide which variables a team commits, which an organization enforces through managed settings, and how to keep credentials out of plain-text env entirely.
## What the env block is Every Claude Code settings file can carry an **`env`** key: an object mapping environment-variable names to **string** values. Claude Code writes each entry into its own process environment, so the value affects Claude Code's behaviour and is inherited by every subprocess it starts — Bash commands, hooks, MCP servers launched over stdio. It is the standard way to apply a variable to every session, or to roll one out to a team through the committed `.claude/settings.json`. ```json { "env": { "API_TIMEOUT_MS": "1200000", "BASH_DEFAULT_TIMEOUT_MS": "300000" } } ``` Values must be strings even when they look like numbers or booleans. ## env versus your shell - **A settings value overwrites the shell.** If your shell exports a variable and an `env` block sets the same one, the settings value applies in most sessions, because Claude Code replaces the inherited value. The exception is a session started by the Claude Desktop app or a self-hosted environment runner, whose launch environment takes precedence over `env` values for variables it already sets. - **You can't remove a variable from settings, only blank it.** To cancel a stale export you can't edit — a `CLAUDE_CODE_USE_VERTEX=1` from a shared shell profile, say — set it to `""`. Claude Code treats the empty value as unset for provider selection; subprocesses still inherit the empty string. - `NO_COLOR` and `FORCE_COLOR` set in `env` reach only subprocesses; Claude Code's own colours follow the shell. ## env across settings files `env` is an ordinary key, so between files it follows the normal precedence: managed, command line (`--settings`), project local, shared project, user. When two files set the same variable, the higher file wins — a managed value beats the same variable in the project file. Environment variables themselves are **not a precedence level**. When a behaviour has both a variable and a dedicated key, the pair decides: `ANTHROPIC_MODEL` is read before the `model` key, while `ANTHROPIC_DEFAULT_MODEL` applies only when nothing sets `model`. ## A worked example A team commits `"BASH_DEFAULT_TIMEOUT_MS": "300000"` to the shared file so long test runs don't time out. One developer exports `BASH_DEFAULT_TIMEOUT_MS=60000` in their shell profile and also sets `"600000"` in their own `.claude/settings.local.json`. In a trusted folder their sessions use `600000`: the local file outranks the shared file, and either file's value replaces the shell export. If the organization's managed settings set the variable, that value wins for everyone. ## Variables a repository can't set A cloned repository shouldn't control where Claude Code writes its files or where session data is exported, so **project and local settings drop** some variables and log a warning visible with `claude --debug`: - directory variables such as `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_TMPDIR`, `HOME`, `TMPDIR` and the `XDG_*` family; - variables that export session content, such as `OTEL_LOG_RAW_API_BODIES`; - the **OpenTelemetry exporter variables** that turn telemetry on or choose its destination, such as `CLAUDE_CODE_ENABLE_TELEMETRY`, `OTEL_METRICS_EXPORTER` and `OTEL_EXPORTER_OTLP_ENDPOINT` — ignored from project and local files only since **v2.1.282**; only off values, such as `none` for an exporter selector, still apply from them; - variables that change how Claude Code starts or syncs, such as `CLAUDE_CODE_PROCESS_WRAPPER`. Set these in your shell, your user settings, managed settings or a `--settings` file instead. A few identity and launch-only variables are ignored from every file. ## When values apply 1. **User, `--settings` and managed `env`:** at startup, and again when a saved change alters the merged block. 2. **Project and local `env`:** after you trust the workspace (or at startup in `-p` mode, which never shows the trust dialog), then again on saved changes. 3. **Variables classified as safe** — model selection, timeouts and limits, feature toggles — at startup from every file. 4. **Removing** a variable from a file doesn't unset it in the running session; that takes effect on the next launch. Features that read their variables once at startup, such as OpenTelemetry monitoring, keep startup values until relaunch. ## Practical guidance | Goal | Where | | :- | :- | | A timeout every teammate needs | `env` in `.claude/settings.json` | | A personal proxy or override | `env` in `~/.claude/settings.json` or the local file | | Telemetry the organization requires | managed settings | | Cancel a stale shell export | `""` in your user file's `env` | | An API credential | a helper such as `apiKeyHelper`, not `env` | `env` values are plain text in the file and reach every subprocess, so they are the wrong place for secrets.
- You delete a variable from the env block during a session. Is it gone?Not yet. Claude Code reapplies new and changed `env` values when you save the file, but removing a variable doesn't unset it in the running session; that takes effect the next time you launch `claude`. Features that read their variables once at startup keep their startup values until relaunch either way.
- A team commits CLAUDE_CODE_ENABLE_TELEMETRY in the shared env block and sees no data on v2.1.286. Why, and where should it go?Since v2.1.282, project and local settings drop the OpenTelemetry variables that turn telemetry on or choose its destination; only off values still apply from them. A local interactive session shows a startup notice, a `-p` run doesn't. Put the variables in user settings, managed settings, the job's environment or a `--settings` file.
- Why not put an API key in env?`env` values are plain text in the settings file and reach every subprocess Claude Code starts. For API credentials, Claude Code provides a helper setting, `apiKeyHelper`, that fetches the value from a command instead of storing it in the file.
- A shell export always beats the settings env block
- Deleting a variable from env unsets it in the running session
- A committed .claude/settings.json can set any variable, CLAUDE_CONFIG_DIR included
- Environment variables are their own level above the command line
- env is a safe place for API keys because only Claude Code reads it
Assumes Claude Code 2.1.286; project and local env blocks ignore the OpenTelemetry exporter variables only since v2.1.282.