Blog · September 22, 2026 · 10 min read · by Vilva Athiban P B

Claude Code Environment Variables: The Groups That Actually Matter

Most people meet Claude Code environment variables the same way: something misbehaves, they search the exact variable name someone mentioned in a thread, and they set it without ever seeing the surrounding map. That works right up until two variables interact, or until one you set in your shell is silently overridden by a settings file.

This is the map. Not all 130-odd variables — the official environment variables reference is the place for the complete list — but the groups that actually come up, plus the rules about precedence and value formats that cause most of the confusion.

First: where to put them

You have two options, and they behave differently.

Your shell — exported from .zshrc, .bashrc or similar. Claude Code reads shell variables at startup, so changes take effect the next time you launch claude.

A settings file — under the env key in a settings.json. Claude Code reads these directly from the file, so they apply no matter how claude was launched, and a running session picks up new and changed values when you save the file. The exception is anything that reads its configuration once at startup, such as OpenTelemetry, which keeps its startup values until you relaunch.

The scopes are ~/.claude/settings.json for you everywhere, .claude/settings.json for everyone on the project and checked into source control, and .claude/settings.local.json for you in this project only.

The precedence rule that catches everyone

When the same variable is set in both your shell and a settings file env block, the settings file wins. Claude Code writes each env entry into the process environment, replacing whatever the shell handed it.

That is the opposite of what a lot of people assume, and it is the single most common reason a variable "does not work". If you exported something in your shell profile and nothing changed, check whether a project settings file is setting the same key.

There is a related trap: in a settings file you can set a variable but you cannot remove one. To neutralise a variable you cannot unset — say a stale provider selection exported by a shell profile you do not control — set it to an empty string in the env block. Claude Code treats the empty value as unset for provider selection, though subprocesses still inherit the empty value.

Between settings files, env values follow normal settings precedence, so a managed (admin-deployed) entry overrides the same variable in user or project settings.

Value formats, and the 1e6 bug worth knowing about

Numeric variables — timeouts, token budgets, retry counts — accept scientific notation and digit separators as well as plain digits. Claude Code reads 2e3 as 2000 and 64_000 as 64000.

This matters historically: before v2.1.211, those spellings could silently set a much smaller value. 1e6 would set a timeout to 1. If you have an old config lying around with scientific notation in it and you have ever wondered why a timeout behaved bizarrely, that is a candidate. A few variables take plain digits only, and their rows say so.

For on/off variables, 1 or true turns the behaviour on and 0 or false turns it off, in any casing. But a handful read only whether you set them at all, so any non-empty value including 0 turns the behaviour on, and you turn it off by unsetting the variable. Those include CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY and DISABLE_ERROR_REPORTING. Setting DISABLE_TELEMETRY=0 does not enable telemetry — it disables it.

Background tasks and long-running work

This group generates a surprising amount of search traffic, mostly because the variable names are long and people encounter them in error messages rather than in docs.

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS — set to 1 to disable all background task functionality, including the run_in_background parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut. Covered in detail in our guide to disabling background tasks.
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP — set to 1 to stop Claude Code terminating background shell commands under memory pressure. By default, on macOS and Linux, it terminates background shells when the OS reports critical memory pressure and the session has been idle for 30 minutes with no turn or subagent running. Windows has no memory-pressure signal, so it has no effect there. We wrote that one up separately.
CLAUDE_AUTO_BACKGROUND_TASKS — force-enable automatic backgrounding of long-running agent tasks, which moves subagents to the background after roughly two minutes.
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS — how many subagents can run in one session before the Agent tool refuses to spawn another (default 20).

Bash timeouts and output limits

If Claude Code keeps killing a build or a test suite partway through, this is the group you want.

BASH_DEFAULT_TIMEOUT_MS — default timeout for long-running bash commands. Default is 120000, or 2 minutes.
BASH_MAX_TIMEOUT_MS — the maximum timeout the model is allowed to set. Default is 600000, or 10 minutes. The effective ceiling is the larger of this and BASH_DEFAULT_TIMEOUT_MS, which is a detail worth re-reading if you raise only one of them and nothing changes.
BASH_MAX_OUTPUT_LENGTH — how many characters of bash output Claude Code reads back into a result. Default 30000, maximum 150000. If you set the bashOutputMaxChars setting, the variable is ignored entirely.
API_TIMEOUT_MS — timeout for API requests. Default 600000.

Thinking and context window

These are the ones most often set for the wrong reason.

CLAUDE_CODE_DISABLE_THINKING=1 omits the thinking parameter from API requests entirely. The docs are explicit that this is a compatibility option for proxies and gateways that reject the parameter — not a way to turn thinking off. On models that think by default, omitting the parameter means the model may still think. To actually disable extended thinking on the Anthropic API, MAX_THINKING_TOKENS=0 is the documented route.

CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 is narrower: it falls back to the fixed thinking budget controlled by MAX_THINKING_TOKENS on the models where adaptive reasoning is optional.

On the context side, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE sets the percentage of the auto-compact window at which compaction triggers, and CLAUDE_CODE_AUTO_COMPACT_WINDOW sets that window in tokens (100000 to 1000000, plain integers only). Both are more useful than people expect for long sessions — see our context management guide for when to reach for them.

Notifications and attention

Two worth knowing if you run Claude Code unattended:

CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK — set to 1 to send the desktop notification even while you are typing in or focused on the terminal. By default Claude Code suppresses it when it thinks you are already watching, which is sensible until you are watching a different pane.
CLAUDE_AFK_TIMEOUT_MS and CLAUDE_AFK_COUNTDOWN_MS — how long an unanswered question dialog waits before auto-continuing without you, and how long before the on-screen countdown appears. Auto-continue is off by default.

Both of these are the local, best-effort layer. If the reason you care is that you have walked away from the machine entirely, terminal notifications are the wrong tool regardless of how you configure them — that is the gap phone notifications exist to cover.

Turning off outbound traffic

In locked-down environments, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is the big hammer. Set to any non-empty value it disables auto-updates, telemetry, error reporting, the /feedback command, release notes, PR and MR status badge checks, and availability checks.

Two caveats. It also disables feature-flag fetching, which quietly changes which features are available to you — so if something stops appearing after you set it, that is the likely cause. And it does not cover official plugin marketplace auto-install, which needs CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL separately.

A sane starting point

If you want one config rather than a tour, this covers most real complaints — long builds getting killed, truncated output, and background shells disappearing on a memory-constrained laptop:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "BASH_MAX_TIMEOUT_MS": "900000",
    "BASH_MAX_OUTPUT_LENGTH": "100000",
    "CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP": "1"
  }
}

Put it in ~/.claude/settings.json if it is a preference, or .claude/settings.json if it is a property of the project — a repo whose test suite genuinely takes eight minutes should say so in the repo, not in every contributor's dotfiles.

When not to set any of this

An honest caveat to close on. Most of these variables exist to work around a specific, diagnosed problem. Setting a pile of them speculatively because a thread recommended it is how you end up with a config nobody can reason about, and with behaviour that diverges from every guide and every colleague.

Change one thing, confirm it fixed the thing you were actually seeing, and leave the rest alone. Version-gated variables in particular — a number of these require a specific Claude Code version or later — fail silently rather than loudly when your version is older, which makes a speculative config extremely hard to debug later.

Keep reading

Desk Exercises for Programmers: 15 Moves to Do While Your AI Agent Codes

7 min read

Exercise While Coding: Turn Claude Code Wait Time Into Micro-Workouts

7 min read

Claude Code Notch Notifications on Mac: See When Claude Is Done Without Watching the Terminal

7 min read

Claude Code Tips and Tricks: 12 Ways to Use Claude Code Effectively

8 min read

Claude Code Multiple Sessions: How to Run Agents in Parallel Without Losing Track

6 min read

A Claude Code Workflow That Doesn't Involve Watching the Terminal

5 min read

Claude Code Hooks: A Practical Guide to Automating Your Agent Workflow

7 min read

Claude Code Auto Mode: Fewer Permission Prompts Without Living Dangerously

7 min read

Claude Code Subagents: How to Delegate Work to Specialized Agents

7 min read

Claude Code Context Management: Treat the Context Window Like a Budget

6 min read

Per-Subagent Model Selection: Route the Grunt Work Down, Keep the Judgment Up Top

7 min read

Skills and Plugins: How to Teach Claude Code Your Way of Working

7 min read

Claude Code Background Tasks: Run Long Commands Without Blocking Your Session

6 min read

Codex CLI Notifications: How to Get a Ding When Codex Is Done or Needs Input

7 min read

Cursor Notification When Done: Every Way to Get Notified When Cursor Finishes

6 min read

Claude Code Notifications: How to Get Notified When Claude Code Finishes or Needs Your Input

6 min read

Want to Be Notified When Claude Responds? How Claude Notifications Work on Web, Desktop, and Mobile

5 min read

Claude Code Notification Scripts: Copy-Paste Recipes for Every Platform

6 min read

Get a Ding the Moment Codex Needs Your Response

6 min read

Get Notified the Moment Claude Code Is Waiting for Your Input

6 min read

“Notifications Are Turned Off for Claude” — Here Is the Fix

6 min read

Codex Sound When Done: Make Codex CLI Play a Sound When It Finishes

6 min read

terminal-notifier + Claude Code: Native macOS Alerts When Your Agent Finishes

6 min read

Gemini CLI Notifications: How to Get a Sound or Alert When Gemini Finishes

6 min read

Get Claude Code Notifications on Your Phone

6 min read

Claude Code Remote Control, Explained

7 min read

preferredNotifChannel: Claude Code's Built-In Notification Setting

6 min read

Claude Code Notifications in tmux and Over SSH

7 min read

Claude Code Effort Levels: Why Your Setting Keeps Getting Ignored

8 min read

Codex vs Claude Code Notifications: How Each One Tells You It Is Done

8 min read

Claude Code Notifications Not Working: A Diagnostic Checklist

10 min read

Claude Code Notifications Inside Your Editor's Terminal

7 min read

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Explained

7 min read

CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP Explained

8 min read

Cursor Alerts Explained: Every Alert Cursor Raises, and How to Control Them

7 min read

Claude Code Notifications on WSL and Windows

9 min read

Claude Code Checkpoints and /rewind

8 min read

Claude Remote Control: How It Works, Turning It Off, and Auto Mode

7 min read

Claude Code /loop: Poll a Deploy, Babysit a PR, and Get Told When It's Done

8 min read

Setting Up NotchFit With OpenAI Codex CLI: Hooks, $notchfit-plan, and the Daily Flow

7 min read

Claude Mods Explained: What the New Plugin Layer Can Do, and How to Turn On 'You Should Know'

9 min read

NotchFit vs Mac Break Reminder Apps: A Clock or a Signal From Your Coding Agent?

8 min read

Claude Code Headless Mode: Running claude -p in Scripts and CI, and the Three Signals That It Finished

10 min read

Building a Movement Habit at a Desk: Use the Agent Run as the Cue, One Set as the Unit, and Streaks Carefully

8 min read

Claude Code MCP Servers Explained: Adding Servers, Choosing a Scope, Handling Secrets, and Why Long Tool Calls Go to the Background

10 min read

/notchfit:plan Explained: How Claude Code or Codex Writes a Weekly Workout Plan the Notch Can Actually Run

8 min read

Claude Code Spinner Verbs Explained: What “Pondering” and “Brewing” Mean, How to Change Them, and Why You Should Stop Watching the Spinner

7 min read

Why NotchFit's Done and Permission Alerts Wait Until Your Set Ends, When That Costs You, and How to Turn the Workout Off

7 min read

How to Resume a Claude Code Session: --continue vs --resume, Naming Sessions, the Session Picker, Branching, and What Comes Back

9 min read

NotchFit on a Mac Without a Notch: How Pill Mode Works on Mac mini, iMac, Mac Studio and a MacBook With the Lid Closed

6 min read

How to Run a Claude Code Session in the Background: /background, claude --bg, Agent View, and Getting Back to It

9 min read

What a Notch App Can See: NotchFit's Local-First Design, What the Claude Code and Codex Hooks Send, and What Stays on Your Mac

7 min read

Why Codex CLI Asks for Permission Every Time, and How to Tune the Sandbox and Approval Policy Without Going Full Access

8 min read

What to Do While Claude Code or Codex Works: A Simple Protocol for the Two-to-Twenty-Minute Gap in Every Agent Run

7 min read

Is It Possible to Get a Notification When Claude Code or Codex Hits a Reset? Yes for Claude Code: the quota_auto_resume Hooks, Explained

8 min read

What a MacBook Notch App Can Actually Do: The Five Kinds of Notch Utility, Their Trade-offs, and Where NotchFit Fits

7 min read

How to Make MCP Servers Not Take Up as Much Context in Claude Code: Tool Search, alwaysLoad, Scopes and Output Caps

8 min read

The notchfit Command Line: Drive Your Workout, Read Status as JSON, Validate Plans and Test the Notch Without Leaving the Terminal

7 min read

How to Audit MCP Tool Calls Made by Claude Code: A Five-Minute Hook Audit Log, OpenTelemetry Tool Events, and the Transcript for Investigations

9 min read

Exercise Snacks: What the Research Actually Says About One-Minute Vigorous Breaks, What It Does Not, and How NotchFit's Agent-Run Sets Compare

8 min read

How Long Until a Claude Code MCP Tool Call Times Out? The Four Timers (Startup, Two-Minute Backgrounding, Idle, Wall-Clock), Their Defaults, and Which One to Change

8 min read

Sitting Too Long as a Developer: The Posture Problems Coding Agents Made Worse, What the Research Says About Breaking Up Sitting, and How NotchFit Turns an Agent Run Into the Break

8 min read

Claude Code .mcp.json Explained: Where Project-Scoped MCP Servers Are Read From, What Happens in Subfolders and Monorepos, and Why a Committed Server Shows Pending Approval

8 min read

Standing Desk Exercises for Developers: Why Standing Still Is Not the Goal, Eight Movements That Fit a Thirty-Second Agent Run, and How NotchFit Cues Them From the Notch

8 min read

The claude mcp Command Reference: add Syntax by Transport, What --scope local, project and user Actually Mean, add-json and add-from-claude-desktop, list, get, remove, login and serve

9 min read

Your First Week With NotchFit: Install and Simulate, Run Real Tasks, Write a Smaller Plan Than You Want, Tune the Alerts, Survive the First Skipped Day, and Decide What Stays

8 min read

How to Stop a Running Claude Code Task: Esc vs Ctrl+C, Background Tasks, Subagents, and Disconnecting Remote Control

8 min read

Pomodoro vs Agent-Driven Breaks: Timing Movement to Claude Code and Codex Runs Instead of a Timer

7 min read

Claude Desktop MCP Configuration: claude_desktop_config.json, Logs, Extensions, and the Difference From Claude Code

9 min read

The 20-20-20 Rule for Developers: Eye Strain, the Evidence, and Agent Runs as the Cue

8 min read

Claude Agent SDK + MCP Servers: mcpServers, allowedTools, Status Checks and Auth

9 min read

Discreet Desk Exercises for an Open-Plan Office While Claude Code Runs

7 min read

claude remote-control Server Mode: Run Claude Code as a Session Server

9 min read

Wrist and Forearm Stretches for Developers: A 60-Second Routine for Every Claude Code Run

7 min read

Claude Remote Control vs Claude Code on the Web: Which to Use and How They Differ

9 min read

Neck and Shoulder Stretches for Developers: A 90-Second Routine Between Agent Runs

7 min read

What Happens When You Step Away From a Claude Code Session: Prompt Cache Expiry, Idle Compaction, and When to Come Back

8 min read

Hip Flexor and Lower Back Stretches for Developers: A Two-Minute Standing Routine Between Agent Runs

7 min read

Claude Code's Monitor Tool: Watch Logs, CI Runs and PRs (Even a WebSocket) and Let Claude React While You Keep Working

7 min read

Hunched Over the Keyboard? Upper-Back (Thoracic) Stretches for Developers: A Two-Minute Seated Routine Between Agent Runs

6 min read

Claude Code Ultrareview: The 15–25 Minute Cloud Review, What to Do While It Runs, and How the Findings Come Back

8 min read

Why Your Legs Go Dead After a Long Claude Code Session: A Two-Minute Standing Calf, Glute and Hamstring Routine Between Agent Runs

7 min read

claude --teleport: Pull a Cloud Session Into Your Terminal, Start One With --cloud, Send Follow-Ups From the CLI, and the Requirements That Trip People Up

8 min read

Rounded Shoulders From Typing? A Two-Minute Chest Opener, Chair Twist and Wall Press Desk Routine for Developers Between Agent Runs

7 min read

Claude Code ultrathink Explained: It Now Runs the Turn at xhigh Effort, How It Differs From /effort, What It Costs in Time, and What to Do While It Runs

7 min read

Best Break Reminder Apps for Mac in 2026: Time Out, Stretchly, BreakTimer, LookAway and NotchFit Compared

7 min read

Claude Code 2.1.319: denyInsteadOfPrompting, MCP Background Tasks and What Changes for Unattended Runs and Notifications

8 min read

Drink Water and Stand Up Cues for Developers: Use Claude Code Agent Runs as Hydration and Standing Reminders

7 min read

Claude Code 2.1.323: Code Mode, Progress Heartbeat, Auto-Mode Fallback and 1M Context — What Changed for Unattended Runs

9 min read

Notch Media Controls on a Mac: What the MacBook Notch Can and Cannot Do, Dynamic Island-Style Apps vs NotchFit

7 min read