Claude Code Environment Variables

Definition

Environment variables are the CLI/API-level configuration surface for Claude Code, covering auth, model selection, token budgets, caching, network, subagents, and observability. Environment variables take precedence over settings files.

Key Points

• Auth & endpoints: ANTHROPIC_API_KEY (overrides subscription), ANTHROPIC_AUTH_TOKEN (custom Bearer), ANTHROPIC_BETAS (beta header), ANTHROPIC_BASE_URL (+ Bedrock/Vertex/Foundry variants) for proxies and gateways.
• Model selection: ANTHROPIC_MODEL (overrides model setting); ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU/FABLE_MODEL resolve the opus/sonnet/haiku/fable aliases (haiku also powers background tasks); ANTHROPIC_CUSTOM_MODEL_OPTION adds gateway-specific entries to /model.
• Token budgets: MAX_THINKING_TOKENS (fixed thinking budget; capped one token below max output, never below 1,024; 0 disables thinking except Fable 5); CLAUDE_CODE_MAX_OUTPUT_TOKENS (default 32000); CLAUDE_CODE_MAX_CONTEXT_TOKENS (override assumed window); TASK_MAX_OUTPUT_LENGTH (subagent output truncation, default 32000 chars); MAX_MCP_OUTPUT_TOKENS (default 25000); CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS.
• Caching: DISABLE_PROMPT_CACHING (+ per-model _OPUS/_SONNET/_HAIKU/_FABLE); ENABLE_PROMPT_CACHING_1H (1h TTL at higher rate; FORCE_PROMPT_CACHING_5M overrides); CLAUDE_CODE_DISABLE_1M_CONTEXT.
• Compaction & effort: DISABLE_AUTO_COMPACT, DISABLE_COMPACT, CLAUDE_CODE_DISABLE_THINKING, CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING, CLAUDE_CODE_EFFORT_LEVEL (low…max/auto, overrides /effort).
• Subagents & limits: CLAUDE_CODE_SUBAGENT_MODEL (all subagents/agent teams/workflows), CLAUDE_CODE_MAX_TURNS, CLAUDE_CODE_MAX_RETRIES + CLAUDE_CODE_RETRY_WATCHDOG.
• Cost: DISABLE_COST_WARNINGS.

Implications

These variables are the programmatic twin of the /effort, /model, and /compact commands in token-usage-reduction: they allow fixed budgets (thinking, output, MCP output), deterministic model routing, and caching policy to be pinned in deployment config rather than left to interactive settings. For teams running agents in CI, MAX_THINKING_TOKENS + CLAUDE_CODE_MAX_OUTPUT_TOKENS + ENABLE_PROMPT_CACHING_1H form the main cost controls.

Open Questions

• Whether CLAUDE_CODE_MAX_CONTEXT_TOKENS interacts correctly with 1M-context models.
• Precise interaction of ENABLE_PROMPT_CACHING_1H with model-specific thresholds.

Related

token-usage-reduction — cost levers these variables pin prompt-caching — the mechanism DISABLE_PROMPT_CACHING / _1H control claude-code-system-prompt — the agent these variables configure claude-code-sessions — session flags must be re-passed on resume

Sources

• raw/external/code-claude-com-env-vars-12397363.md