AI Assistant

Feature Flags

Claude Code uses a two-layer feature gating system: build-time flags for compile-time tree-shaking and environment variables for runtime behavior.

Build-Time Flags

Build-time flags use feature() from bun:bundle, which evaluates to a boolean constant at compile time. The bundler eliminates unreachable branches entirely, so gated code never appears in the output binary.

import { feature } from 'bun:bundle'

if (feature('COORDINATOR_MODE')) {
  // This entire block is removed from external builds
  const module = require('./coordinator/coordinatorMode.js')
}

Because feature() resolves at compile time, the gated code path must use require() (not static import) to prevent the bundler from including the module in the dependency graph when the flag is off.

Flag List

FlagPurpose
COORDINATOR_MODEMulti-agent coordinator that dispatches work to sub-agents
KAIROSAssistant/teammate mode for persistent background agents
KAIROS_BRIEFBrief/summary panel for Kairos sessions
KAIROS_GITHUB_WEBHOOKSGitHub PR subscription for Kairos agents
KAIROS_PUSH_NOTIFICATIONPush notifications for Kairos events
VOICE_MODESpeech-to-text and text-to-speech voice input
WORKFLOW_SCRIPTSReusable workflow script execution
MONITOR_TOOLSystem monitoring tool for agent health
UDS_INBOXUnix domain socket peer discovery
HISTORY_SNIPManual transcript snipping tool
TRANSCRIPT_CLASSIFIERML-based permission classifier using transcript analysis
BASH_CLASSIFIERML-based bash command risk classifier
CACHED_MICROCOMPACTCached micro-compaction for efficient context management
PROMPT_CACHE_BREAK_DETECTIONDetect and handle prompt cache invalidation
BREAK_CACHE_COMMANDForce cache break via command injection
CONNECTOR_TEXTConnector text blocks in API responses
QUICK_SEARCHGlobal file search and quick-open commands
TERMINAL_PANELEmbedded terminal panel toggle
MESSAGE_ACTIONSMessage action menu on shift+up
PROACTIVEProactive agent suggestions
COMMIT_ATTRIBUTIONGit commit co-author attribution tracking
TEAMMEMTeam memory synchronization
CONTEXT_COLLAPSEContext window collapse optimization
NATIVE_CLIENT_ATTESTATIONNative client attestation headers
ANTI_DISTILLATION_CCAnti-distillation protections
EXPERIMENTAL_SKILL_SEARCHSkill search during compaction
COWORKER_TYPE_TELEMETRYCoworker type in analytics metadata

How Flags Affect Tool Availability

Feature flags control which tools are registered at startup:

// tools.ts
const MonitorTool = feature('MONITOR_TOOL')
  ? require('./tools/MonitorTool.js') : null

const SnipTool = feature('HISTORY_SNIP')
  ? require('./tools/SnipTool.js') : null

const ListPeersTool = feature('UDS_INBOX')
  ? require('./tools/ListPeersTool.js') : null

const WorkflowTool = feature('WORKFLOW_SCRIPTS')
  ? require('./tools/WorkflowTool.js') : null

Coordinator mode conditionally adds delegation tools:

if (feature('COORDINATOR_MODE') && coordinatorModeModule?.isCoordinatorMode()) {
  // Add CoordinatorTool, WorkerDoneTool, etc.
}

How Flags Affect Command Registration

Similarly, slash commands are conditionally registered:

// commands.ts
const voiceCommand = feature('VOICE_MODE')
  ? require('./commands/voice.js') : null

const forceSnip = feature('HISTORY_SNIP')
  ? require('./commands/snip.js') : null

const workflowsCmd = feature('WORKFLOW_SCRIPTS')
  ? require('./commands/workflows.js') : null

const peersCmd = feature('UDS_INBOX')
  ? require('./commands/peers.js') : null

Environment Variables

Runtime environment variables provide a second layer of feature gating that does not require rebuilding:

CLAUDE_CODE_SIMPLEboolean env

Activates bare/simple mode. Disables skills in prompts, memory directory, file edit previews, and agent directory loading. Set automatically by --bare flag and in coordinator worker sub-processes.

CLAUDE_CODE_COORDINATOR_MODEboolean env

Enables coordinator mode at runtime (requires the COORDINATOR_MODE build flag). The coordinator spawns worker agents and dispatches tasks.

CLAUDE_CODE_DISABLE_THINKINGboolean env

Disables extended thinking/reasoning in API calls. When set, the API is called without thinking parameters regardless of user preferences.

CLAUDE_CODE_DISABLE_AUTO_MEMORYboolean env

Disables automatic memory extraction and storage.

CLAUDE_CODE_DISABLE_BACKGROUND_TASKSboolean env

Disables background task processing.

DISABLE_INTERLEAVED_THINKINGboolean env

Disables interleaved thinking blocks in API responses.

DISABLE_COMPACTboolean env

Disables conversation compaction entirely.

DISABLE_AUTO_COMPACTboolean env

Disables automatic compaction triggers while allowing manual /compact.

Boolean environment variables are checked with isEnvTruthy(), which treats "1", "true", and "yes" as truthy. The variables listed above are cleared from the environment at CLI entry (entrypoints/cli.tsx) to prevent accidental inheritance by child processes.

Two-Layer Interaction

Build-time and runtime flags often work together. For example, coordinator mode requires both layers:

// Build-time: include the coordinator module
const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js')
  : null

// Runtime: check if coordinator mode is active
if (feature('COORDINATOR_MODE') &&
    isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)) {
  coordinatorModeModule.enableCoordinatorMode()
}

The build-time flag controls whether the code exists in the binary. The environment variable controls whether it activates at runtime. This two-layer approach ensures that:

  1. External builds have no coordinator code at all (smaller binary, no leakage)
  2. Internal builds can toggle the feature without recompiling
  3. Worker sub-processes can opt into simplified mode via environment variables
Cost & History Previous