This document describes the feature flag system used throughout Codex to gate experimental, optional, and platform-specific functionality. Feature flags enable progressive feature rollout through well-defined lifecycle stages and provide users with fine-grained control over which capabilities are active in their sessions.
For information about configuring individual features, see the Configuration System (2.2)
The feature flag system centralizes toggles for experimental and optional behavior across the codebase. Instead of scattering boolean configuration fields throughout multiple modules, Codex defines features in a centralized registry with consistent metadata including lifecycle stage, default state, and canonical key.
Features are managed through the Features struct codex-rs/features/src/lib.rs242 which maintains an enabled set and tracks legacy usage patterns for deprecation warnings. The system supports multiple configuration sources with well-defined precedence, automatic dependency resolution, and graceful handling of deprecated feature keys via LegacyFeatureToggles codex-rs/features/src/lib.rs33
Sources: codex-rs/features/src/lib.rs1-35 codex-rs/features/src/lib.rs242-260
Each feature progresses through a defined lifecycle, represented by the Stage enum codex-rs/features/src/lib.rs38-53 The stage determines visibility, stability guarantees, and user-facing presentation.
Title: Feature Flag Lifecycle Stages
| Stage | Visibility | Default State | Purpose |
|---|---|---|---|
UnderDevelopment | Internal only | false | Features still under development, not ready for external use codex-rs/features/src/lib.rs40 |
Experimental | /experimental menu | false | Experimental features made available through the UI codex-rs/features/src/lib.rs42-46 |
Stable | Standard config | Varies | Stable features; flag kept for ad-hoc toggling codex-rs/features/src/lib.rs48 |
Deprecated | Standard config | false | Feature should no longer be used codex-rs/features/src/lib.rs50 |
Removed | Config compat | false | Useless flag kept for backward compatibility codex-rs/features/src/lib.rs52 |
Sources: codex-rs/features/src/lib.rs38-81
All features are defined in the Feature enum codex-rs/features/src/lib.rs85-226 This registry maps internal logic to user-facing keys.
Title: Mapping Feature Enums to Registry Metadata
The registry includes a wide variety of capabilities:
ShellTool codex-rs/features/src/lib.rs88 CodexHooks codex-rs/features/src/lib.rs90CodeMode codex-rs/features/src/lib.rs96 UnifiedExec codex-rs/features/src/lib.rs104 NetworkProxy codex-rs/features/src/lib.rs150 UseLegacyLandlock codex-rs/features/src/lib.rs132MultiAgentV2 codex-rs/features/src/lib.rs156 Collab codex-rs/features/src/lib.rs154Apps codex-rs/features/src/lib.rs162 EnableMcpApps codex-rs/features/src/lib.rs164 Plugins codex-rs/features/src/lib.rs176Sources: codex-rs/features/src/lib.rs85-226 codex-rs/features/src/tests.rs1-15
Features are integrated into the primary configuration system. The ConfigToml struct includes a features field which holds a FeaturesToml codex-rs/config/src/config_toml.rs150-201
Title: Feature Flag Configuration Precedence
Features table in config.toml:
The FeaturesToml struct codex-rs/features/src/lib.rs69 allows users to enable/disable specific keys. It also supports complex feature-specific configuration blocks via FeatureToml::Config codex-rs/features/src/lib.rs232
Cloud-Managed Requirements:
The system can load FeatureRequirementsToml codex-rs/core/src/config/mod.rs16 which enforces specific feature states regardless of user preference, often used for security policies.
Sources: codex-rs/config/src/config_toml.rs150-201 codex-rs/core/src/config/mod.rs9-30 codex-rs/core/src/session/config_lock.rs149-159
During a session, feature state is materialized into the Config and accessed via the features.enabled(Feature::...) pattern codex-rs/core/src/session/config_lock.rs158
The system handles dependencies between flags. For instance, CodeModeOnly automatically requires CodeMode during normalization codex-rs/features/src/tests.rs79-86
Some features require complex structured data defined in feature_configs.rs:
MultiAgentV2ConfigToml: Configures routing, timeouts, and hints for sub-agents codex-rs/features/src/feature_configs.rs74-114CodeModeConfigToml: Configures the V8 execution environment and tool namespaces codex-rs/features/src/feature_configs.rs9-20TokenBudgetConfigToml: Configures token reminders and auto-compaction fallback prompts codex-rs/features/src/feature_configs.rs128-152NetworkProxyConfigToml: Configures the managed network proxy for sandboxed sessions codex-rs/features/src/feature_configs.rs205-224Sources: codex-rs/features/src/feature_configs.rs7-224 codex-rs/features/src/tests.rs79-86 codex-rs/core/src/session/config_lock.rs156-166
The feature system maintains backwards compatibility for renamed or restructured feature keys through legacy_feature_keys codex-rs/features/src/lib.rs34
| Legacy Key | Current Feature | Context |
|---|---|---|
telepathy | Feature::Chronicle | Legacy alias for the Chronicle sidecar codex-rs/features/src/tests.rs213-216 |
collab | Feature::Collab | Alias for multi-agent capabilities codex-rs/features/src/tests.rs219-222 |
codex_hooks | Feature::CodexHooks | Alias for Claude-style hooks codex-rs/features/src/tests.rs225-228 |
tool_search | Feature::ToolSearch | Removed compatibility flag codex-rs/features/src/lib.rs169-170 |
Sources: codex-rs/features/src/tests.rs213-228 codex-rs/features/src/lib.rs154-170
Features in the Experimental stage are surfaced to users via the /experimental menu in the TUI.
experimental_menu_name(): Returns the display name for the UI codex-rs/features/src/lib.rs56-61experimental_menu_description(): Returns help text for the user codex-rs/features/src/lib.rs63-70experimental_announcement(): Optional text shown when the feature is first toggled codex-rs/features/src/lib.rs72-80Sources: codex-rs/features/src/lib.rs55-81
Feature states are a critical part of the session contract and are persisted in the ConfigLockfileToml codex-rs/core/src/session/config_lock.rs77-81
When a session is replayed, the materialize_resolved_enabled function codex-rs/core/src/session/config_lock.rs155 ensures that the features active during the original run are restored, preventing drift when defaults change between versions.
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.