Feature Flags#
Claude Code gates experimental and optional functionality through environment variable-based feature flags — there is no centralized flag registry or config file. Each flag is a discrete CLAUDE_CODE_* (or related prefix) environment variable read at startup.
Three deployment stages appear in the changelog:
- Research preview / opt-in — feature is off by default; set a specific env var to enable (e.g.,
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). - Default-on with opt-out — feature ships enabled; set an env var to disable (e.g.,
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0). - Graduated (GA) — flag removed; feature is unconditionally available (e.g., Auto mode no longer requires
--enable-auto-mode) .
Important caveat: Feature flags are read during early startup and cached to disk. A bug caused stale cached values to persist across sessions; this was fixed in v2.1.70. When a flag isn't taking effect, restart Claude Code to force a fresh read.
When a background session or --bg rejects a flag-gated feature, the rejection message names the specific gate (non-TTY, env var, or managed setting), making it easier to diagnose which condition is blocking the feature.
Feature Flag Catalog#
Opt-in / Research Previews#
These flags enable features that are off by default:
| Environment Variable | Effect | Introduced |
|---|---|---|
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 | Multi-agent collaboration (token-intensive) | v2.1.32 |
CLAUDE_CODE_NO_FLICKER=1 | Flicker-free alt-screen renderer with virtualized scrollback | v2.1.89 |
CLAUDE_CODE_FORK_SUBAGENT=1 | Forked subagents in non-interactive SDK sessions | v2.1.117 |
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 | Gateway /v1/models discovery for the /model picker (was automatic in v2.1.126–2.1.128, then moved to opt-in) | v2.1.129 |
ENABLE_TOOL_SEARCH | MCP tool search on Vertex AI (disabled there by default) | — |
ENABLE_PROMPT_CACHING_1H | 1-hour prompt cache TTL on API key, Bedrock, Vertex, and Foundry | v2.1.108 |
CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 | Pin fast mode to Opus 4.6 instead of 4.7 | v2.1.142 |
CLAUDE_CODE_USE_POWERSHELL_TOOL=1 | Enable PowerShell tool on Linux/macOS (requires pwsh) | v2.1.111 |
Opt-out Flags (default-on features)#
These flags disable features that are on by default:
| Environment Variable | Effect | Introduced |
|---|---|---|
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0 | Disable session recap | v2.1.110 |
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 | Strip experimental beta API headers; fixes proxy/gateway compatibility | v2.1.81 |
CLAUDE_CODE_ENABLE_TASKS=false | Keep old task system (temporary escape hatch) | v2.1.19 |
CLAUDE_CODE_DISABLE_1M_CONTEXT | Disable 1M context window support | v2.1.50 |
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS | Disable background task functionality and Ctrl+B | v2.1.4 |
DISABLE_UPDATES | Block all update paths including manual claude update | v2.1.118 |
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK | Disable fallback to non-streaming when streaming fails | v2.1.83 |
ENABLE_CLAUDEAI_MCP_SERVERS=false | Opt out of claude.ai MCP servers | v2.1.63 |
Enterprise / Observability Flags#
These flags expose additional enterprise monitoring or survey features:
| Environment Variable | Effect | Introduced |
|---|---|---|
CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL | Re-enable session quality survey for enterprises capturing via OpenTelemetry | v2.1.136 |
OTEL_LOG_USER_PROMPTS | Include user prompt text in OTel spans (sensitive; opt-in) | v2.1.101 |
OTEL_LOG_TOOL_DETAILS | Include tool parameter details in OTel events | v2.1.101 |
OTEL_LOG_RAW_API_BODIES | Emit full API request/response bodies as OTel log events | v2.1.111 |
OTEL_METRICS_INCLUDE_ENTRYPOINT=true | Add session entrypoint as OTel metric attribute | v2.1.152 |
Graduated Features (flags removed)#
Some features that began as flags have since become unconditional:
- Agent View (
claude agents) — introduced as research preview in v2.1.139 ; no flag required today. - Auto mode — previously required
--enable-auto-mode; now available by default . - Channels (
--channels) — added as research preview in v2.1.80 ; graduated since. CLAUDE_CODE_NO_FLICKER=1— flicker-free renderer was opt-in (v2.1.89), then became available as/tui fullscreen, then the default renderer .
Discovery and Debugging#
There is no centralized flag registry. The authoritative source for all feature flags is CHANGELOG.md, which documents each flag at introduction, modification, and removal.
Finding flags:
- Search
CHANGELOG.mdforCLAUDE_CODE_orenv varto find flags near their introduction dates. - The
/doctorcommand surfaces some configuration issues and flag states at runtime. claude agents/--bgrejection messages name the specific gate (non-TTY, env var, or setting) blocking a feature .
Debugging stale flag values:
Flag values are read at early startup and cached to disk. If a flag change isn't taking effect, restart Claude Code to force a fresh read. This was a documented bug fixed in v2.1.70: "Fixed feature flags read during early startup never refreshing their disk cache, causing stale values to persist across sessions."
Setting flags:
Flags can be set as shell environment variables before invocation, or through the env block in settings.json to persist them across sessions. Provider-specific flags (e.g., CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX) follow the same convention but control API routing rather than feature gating.
