Feature Flags (Build-Time)

• Entity ID: ent-20260410-4e2d6754780c
• Type: concept
• Scope: shared
• Status: active

Description

Claude Code uses build-time feature flags to gate entire subsystems, tools, commands, and code paths. The mechanism centers on a feature(name) function imported from the bun:bundle module. In production Bun builds, feature() calls resolve to compile-time boolean constants, and Bun's bundler performs dead-code elimination (DCE): code inside inactive if (feature('FLAG')) branches is stripped entirely from the output, including any string literals, require() calls, and GrowthBook flag references those branches contain. This prevents Anthropic-internal feature names from leaking into external builds.

In development, the bun:bundle import is intercepted by a Bun preload plugin (scripts/bun-plugin-shims.ts) that resolves it to src/shims/bun-bundle.ts. This shim maintains a FEATURE_FLAGS map where each flag reads from an environment variable (e.g., CLAUDE_CODE_PROACTIVE) via the envBool() helper, defaulting to false. For the esbuild-based production build (scripts/build-bundle.ts), bun:bundle is aliased to the same shim file.

The codebase contains approximately 91 distinct feature flags referenced via feature() calls. Flags gate behavior at multiple levels: CLI entrypoint routing, slash-command registration, tool availability, system prompt composition, keybinding registration, UI component rendering, and module-level conditional require() imports.

Two-layer gating pattern

Many features use a two-layer gating pattern: a build-time feature() check (eliminates dead code) wrapping a runtime GrowthBook/Statsig check (controls rollout and kill-switch). The code comments refer to a "positive ternary pattern" where the feature check is written as return feature('X') ? runtimeCheck() : false rather than if (!feature('X')) return; ..., because the negative pattern fails to eliminate inline string literals from external builds.

Flag categories

Always-on subsystem flags (registered in the shim with env-var fallbacks):

Additional flags found only via feature() calls in source (not in the shim -- likely defined in internal Bun build configs or added after the shim snapshot):

AGENT_MEMORY_SNAPSHOT, AGENT_TRIGGERS_REMOTE, ALLOW_TEST_VERSIONS, ANTI_DISTILLATION_CC, AUTO_THEME, AWAY_SUMMARY, BASH_CLASSIFIER, BREAK_CACHE_COMMAND, BUILDING_CLAUDE_APPS, BUILTIN_EXPLORE_PLAN_AGENTS, BYOC_ENVIRONMENT_RUNNER, CACHED_MICROCOMPACT, CCR_AUTO_CONNECT, CCR_MIRROR, CHICAGO_MCP, COMMIT_ATTRIBUTION, COMPACTION_REMINDERS, CONNECTOR_TEXT, CONTEXT_COLLAPSE, COWORKER_TYPE_TELEMETRY, DIRECT_CONNECT, DOWNLOAD_USER_SETTINGS, ENHANCED_TELEMETRY_BETA, EXTRACT_MEMORIES, FILE_PERSISTENCE, HARD_FAIL, HISTORY_PICKER, HOOK_PROMPTS, IS_LIBC_GLIBC, IS_LIBC_MUSL, KAIROS_CHANNELS, KAIROS_DREAM, KAIROS_PUSH_NOTIFICATION, LODESTONE, MCP_RICH_OUTPUT, MEMORY_SHAPE_TELEMETRY, MESSAGE_ACTIONS, NATIVE_CLIENT_ATTESTATION, NATIVE_CLIPBOARD_IMAGE, NEW_INIT, OVERFLOW_TEST_TOOL, PERFETTO_TRACING, POWERSHELL_AUTO_MODE, PROMPT_CACHE_BREAK_DETECTION, QUICK_SEARCH, REVIEW_ARTIFACT, RUN_SKILL_GENERATOR, SELF_HOSTED_RUNNER, SHOT_STATS, SKILL_IMPROVEMENT, SLOW_OPERATION_LOGGING, SSH_REMOTE, STREAMLINED_OUTPUT, TEAMMEM, TEMPLATES, TERMINAL_PANEL, TOKEN_BUDGET, TRANSCRIPT_CLASSIFIER, TREE_SITTER_BASH, TREE_SITTER_BASH_SHADOW, ULTRATHINK, UNATTENDED_RETRY, UPLOAD_USER_SETTINGS, VERIFICATION_AGENT, WEB_BROWSER_TOOL

How flags gate code

Flags control behavior at several architectural layers:

1. CLI entrypoint routing (src/entrypoints/cli.tsx): Flags like DAEMON, BRIDGE_MODE, BG_SESSIONS, and DUMP_SYSTEM_PROMPT gate entire CLI subcommands before the main application loads.

2. Slash-command registration (src/commands.ts): Each flag-gated command uses a conditional require() that resolves to null when the flag is off. The command array filters out nulls.

3. Tool availability (src/tools.ts, src/constants/tools.ts): Tools like MonitorTool, WorkflowTool, SnipTool, ListPeersTool, CronCreateTool, SendUserFileTool, WebBrowserTool, and TerminalCaptureTool are conditionally require()'d and included in tool lists only when their flag is active.

4. System prompt composition (src/constants/prompts.ts): Prompt sections for proactive behavior, brief mode, and skill search are conditionally included based on flag state.

5. Keybinding registration (src/keybindings/defaultBindings.ts): Push-to-talk (VOICE_MODE), brief-mode shortcuts (KAIROS/KAIROS_BRIEF), and terminal toggle (TERMINAL_PANEL) are conditionally added.

6. Module-level conditional require (throughout): The dominant pattern is const Foo = feature('FLAG') ? require('./Foo.js').Foo : null, which ensures the entire module subtree is eliminated by DCE when the flag is off.

7. UI component rendering (src/components/): Components like CompanionSprite (BUDDY), ChannelsNotice (KAIROS_CHANNELS), WebBrowserPanel (WEB_BROWSER_TOOL), and VoiceIndicator (VOICE_MODE) are conditionally rendered or entirely skipped.

Relationship to process.env.USER_TYPE

A parallel gating mechanism uses process.env.USER_TYPE (set to "external" via define in the build config). This gates Anthropic-internal ("ant") tools and packages (e.g., REPLTool, SuggestBackgroundPRTool, @ant/* packages) and is handled by esbuild's define replacements rather than the bun:bundle feature system. Both mechanisms achieve DCE but serve different purposes: USER_TYPE separates internal vs. external builds, while feature flags control incremental feature rollout.

Key claims

• The feature() function from bun:bundle returns a compile-time boolean in production Bun builds; inactive branches and all their contents (string literals, require calls, GrowthBook flag names) are stripped by dead-code elimination.
• In development, bun:bundle is shimmed via a Bun preload plugin to src/shims/bun-bundle.ts, which reads each flag from an environment variable (pattern: CLAUDE_CODE_<FLAG_NAME>) with false as default.
• The esbuild production build (scripts/build-bundle.ts) aliases bun:bundle to the same shim and uses define replacements for MACRO.* constants and process.env.USER_TYPE.
• Approximately 91 distinct feature flags are referenced across the codebase, with 24 registered in the dev shim and the remainder defined in internal build configurations.
• The "positive ternary pattern" (return feature('X') ? check() : false) is required instead of early-return guards to ensure string literal elimination in external builds.
• Many flags use two-layer gating: build-time feature() for DCE, plus a runtime GrowthBook/Statsig gate for gradual rollout and kill-switches.
• ABLATION_BASELINE is hardcoded to false in external builds and is never env-configurable, serving as a harness-science mechanism for internal experimentation.
• COORDINATOR_MODE requires both the build-time feature flag AND the CLAUDE_CODE_COORDINATOR_MODE runtime env var to be truthy.

Relations

• depends-on bun:bundle module (Bun's bundler compile-time constant system)
• depends-on src/shims/bun-bundle.ts (dev/esbuild shim providing runtime flag resolution)
• depends-on scripts/bun-plugin-shims.ts (Bun preload plugin intercepting bun:bundle imports)
• depends-on scripts/build-bundle.ts (esbuild production build config with alias and define)
• interacts-with GrowthBook / Statsig (runtime feature gates used inside build-time flag guards)
• interacts-with process.env.USER_TYPE gating (parallel DCE mechanism for internal vs. external builds)

Sources

• src/shims/bun-bundle.ts -- dev shim defining 24 feature flags with env-var resolution and the feature() export
• src/types/bun-bundle.d.ts -- TypeScript declaration for the bun:bundle module's feature() function
• scripts/bun-plugin-shims.ts -- Bun preload plugin that intercepts bun:bundle imports
• scripts/build-bundle.ts -- esbuild production build script with bun:bundle alias and define replacements
• bunfig.toml -- Bun config referencing the preload plugin
• src/entrypoints/cli.tsx -- CLI entrypoint with feature-gated subcommand routing
• src/commands.ts -- slash-command registration with conditional requires per flag
• src/tools.ts -- tool registration with conditional requires per flag
• src/constants/tools.ts -- tool-list construction gated by WORKFLOW_SCRIPTS and AGENT_TRIGGERS
• src/constants/prompts.ts -- system prompt composition gated by PROACTIVE, KAIROS, EXPERIMENTAL_SKILL_SEARCH
• src/bridge/bridgeEnabled.ts -- two-layer gating example: feature('BRIDGE_MODE') + GrowthBook tengu_ccr_bridge
• src/voice/voiceModeEnabled.ts -- two-layer gating example: feature('VOICE_MODE') + GrowthBook kill-switch
• src/coordinator/coordinatorMode.ts -- two-layer gating: feature('COORDINATOR_MODE') + runtime env var