Claude Code Environment Variables: Configuration, Scope and Safe Verification

Claude Code reads environment variables from several sources: the shell environment, project-level .env files, and settings in its own configuration. Knowing which source wins, and how to verify what Claude actually sees, prevents silent misconfigurations. Tools like fenbs keep the nonsecret configuration decisions — which variables mean what, and which value was agreed — in a shared record the whole team can read.

This guide covers where Claude Code finds variables, how precedence works, how to check the values safely, and how to share team configuration without exposing secrets.

Where Claude Code looks for environment variables

Claude Code inherits the environment of the shell that launches it. Any variable you set with export before running claude is available inside the session. This includes ANTHROPIC_API_KEY, model overrides, and any application-specific variables your project needs.

It also reads .env files in the project directory. Variables in .env are loaded when Claude Code starts, making them available without a manual export. A .env.local file, if present, is typically read as well and can override the base .env.

Finally, Claude Code's own settings files (in ~/.claude/) can set model choices and behavior flags. These act as defaults that shell or project variables can override. For an overview of how Claude Code is installed and configured, see how to install Claude Code.

Precedence: which value wins

When the same variable appears in more than one place, the most specific source wins. In practice the order from lowest to highest priority is:

1. Claude Code settings files in ~/.claude/ — the global defaults.
2. The project .env file — applies to everyone working in that project directory.
3. A .env.local file — overrides the project .env for a single developer's machine.
4. The shell environment at launch time — wins over all file-based values.

This order means a developer can override a project default locally without touching a shared file. It also means a stale shell variable can silently override a carefully chosen project value. The most common confusion is a variable set in a previous session that is still in the shell when Claude Code starts.

If something behaves differently on one machine than another, a differing shell variable is often the cause. Clear the shell variable and restart Claude Code to confirm.

How to verify what Claude Code actually sees

Ask Claude Code to run a command that prints the variable you want to check. On macOS and Linux:

echo $VARIABLE_NAME

Do not print secret variables this way. The output appears in the conversation and may end up in session history. For a key or token, check that it is set (exit code zero) rather than printing its value:

[ -n "$ANTHROPIC_API_KEY" ] && echo "set" || echo "not set"

You can also ask Claude Code to describe its current model and any active settings. A missing or wrong ANTHROPIC_API_KEY surfaces as an authentication error rather than a subtle wrong answer, which makes it easier to spot. For sandboxing and isolation options, see Claude Code sandbox.

Which variables are sensitive and which are not

API keys, tokens and passwords are sensitive. They must stay in .env.local (unversioned) or in the shell, never in a shared .env file or in a tool like fenbs. A .gitignore entry for .env.local is the standard guard.

Configuration decisions are not sensitive: which model to use by default, whether to enable a particular feature flag, the project's API base URL, log level and similar. These can go in a versioned .env file and benefit from being recorded as team decisions. When someone changes them, the reason matters.

The distinction is practical: a secret gives access to a system; a configuration value describes how to use it. Keep them in different files and handle them differently.

How teams share configuration decisions safely

A versioned .env.example file lists every variable the project needs, with placeholder values and a short comment explaining each. A new developer copies it to .env.local, fills in their own secrets, and leaves the project defaults for everything else.

When a variable's meaning or agreed value changes, update the .env.example comment and record the change as a decision in fenbs. The next developer or AI session can read what was decided and why, without having to ask.

For larger teams, a secrets manager (AWS Secrets Manager, HashiCorp Vault, or similar) handles the sensitive side and keeps secrets out of developer machines entirely. For Claude Code specifically, any variable named in Claude Code docs has an Anthropic-published meaning; custom variables are yours to document.

Recording variable names and their agreed behavior as context notes in a shared record means a connected assistant reads that information at the start of each session. It understands which model override is expected and which feature flags are active, without needing a fresh explanation each time.

Common problems and how to fix them

Claude Code uses the wrong model: check for a ANTHROPIC_MODEL or --model override in the shell environment. A value set days ago in a long-running shell session may still be active.

A variable works on one machine but not another: the most likely cause is a value in .env.local on the first machine that does not exist on the second. Compare the two .env.local files.

A secret is unexpectedly missing: check whether the .env.local file was created after Claude Code was started. Variables in a newly created file are not picked up by an already-running process; restart Claude Code.

How to do this with fenbs

1. Create a free account and add the project.
2. Add the nonsecret configuration decisions as Decisions and rules: the variable name, its agreed value or range, and who decided it.
3. Add a context note listing the variables the project uses and what each one does, without their values.
4. Connect Claude Code from Integrations and ask it to read the project context at the start of each session.
5. When a configuration decision changes, update the record in fenbs before or alongside the change in .env.example.

Never put actual secret values in fenbs. The rule is: if it gives access, it stays in a secrets file or manager. If it describes behavior, it belongs in the shared record.