Skip to main content

​
Overview

Feature flags allow you to enable experimental and optional functionality in Codex. Features progress through different stages: under development, experimental, stable, deprecated, and removed.

​
Enabling Features

You can enable features in three ways:
Use the --enable flag:
codex --enable js_repl
codex --enable multi_agent --enable apps

​
Disabling Features

Disable features that are enabled by default:
Use the --disable flag:
codex --disable shell_tool
codex --disable unified_exec --disable undo

​
Managing Features

The features subcommand helps you manage feature flags:

​
List All Features

codex features list
Displays all available features with their stage and current state: 
apps                      experimental     false
js_repl                   experimental     false
multi_agent               experimental     false
shell_tool                stable           true
unified_exec              stable           true
undo                      stable           false

​
Enable a Feature

codex features enable js_repl
This updates your config.toml file to enable the feature.

​
Disable a Feature

codex features disable shell_tool
This updates your config.toml file to disable the feature.

​
Experimental Features

Experimental features are accessible through the /experimental menu in the interactive TUI. Here are the currently available experimental features:

​
JavaScript REPL

​
js_repl
boolean
default:"false"
Enable a persistent Node-backed JavaScript REPL for interactive website debugging and other inline JavaScript execution capabilities.Requirements:
  • Node.js >= v22.22.0
Example:
codex --enable js_repl

​
Multi-Agents

​
multi_agent
boolean
default:"false"
Allow Codex to spawn multiple agents to parallelize work and improve efficiency.Example:
codex --enable multi_agent "refactor the entire codebase"
The legacy key collab is also accepted but deprecated. Use multi_agent instead.

​
Apps (ChatGPT Connectors)

​
apps
boolean
default:"false"
Use connected ChatGPT Apps using ”$” mentions. Install Apps via the /apps command.Example:
codex --enable apps
After enabling, restart Codex and use:
$AppName help me with X

​
Bubblewrap Sandbox (Linux)

​
use_linux_sandbox_bwrap
boolean
default:"false"
Use the new Linux sandbox based on bubblewrap for stronger filesystem and network controls.Platform: Linux onlyBenefits:
  • Keeps .git and .codex read-only inside writable workspaces
  • Stronger controls than Landlock alone
Example:
codex --enable use_linux_sandbox_bwrap

​
Prevent Sleep While Running

​
prevent_idle_sleep
boolean
default:"false"
Keep your computer awake while Codex is running a thread.Platforms: macOS, Linux, WindowsExample:
codex --enable prevent_idle_sleep

​
Stable Features

Stable features are production-ready and enabled by default:
Enable the default shell tool for command execution.Default: EnabledDisable if you want to prevent all shell command execution:
codex --disable shell_tool
Use the single unified PTY-backed exec tool for command execution.Default: Enabled (except on Windows)Provides better handling of interactive commands and consistent behavior across platforms.
Enable shell snapshotting to track environment changes.Default: EnabledHelps track shell state changes between commands.
Persist rollout metadata and session state to a local SQLite database.Default: EnabledLocation: ~/.codex/state.db
Enable personality selection in the TUI.Default: EnabledAllows customizing the agent’s communication style.
Enforce UTF-8 output in PowerShell.Default: Enabled (Windows only)Ensures consistent text encoding on Windows.
Compress request bodies (zstd) when sending streaming requests to codex-backend.Default: EnabledReduces bandwidth usage for large requests.
Allow prompting and installing missing MCP dependencies.Default: EnabledAutomatically handles MCP server dependencies.
Create a ghost commit at each turn for easy undo.Default: DisabledEnable with:
codex --enable undo
When enabled, you can undo changes by resetting to the previous ghost commit.

​
Under Development Features

Under-development features are incomplete and may behave unpredictably. They are not shown in the /experimental menu and should only be enabled for testing purposes.
These features are actively being developed:
  • js_repl_tools_only - Only expose js_repl tools directly to the model
  • shell_zsh_fork - Route shell tool execution through the zsh exec bridge
  • apply_patch_freeform - Include the freeform apply_patch tool
  • request_permissions - Request additional filesystem permissions while sandboxed
  • codex_git_commit - Enable git commit attribution guidance
  • runtime_metrics - Enable runtime metrics snapshots
  • memories - Enable startup memory extraction and file-backed consolidation
  • child_agents_md - Append additional AGENTS.md guidance to user instructions
  • apps_mcp_gateway - Route apps MCP calls through the configured gateway
  • skill_env_var_dependency_prompt - Prompt for missing skill env var dependencies
  • default_mode_request_user_input - Allow request_user_input in Default collaboration mode
  • voice_transcription - Enable voice transcription in the TUI composer
  • realtime_conversation - Enable experimental realtime voice conversation mode
  • responses_websockets - Use Responses API WebSocket transport for OpenAI by default
  • responses_websockets_v2 - Enable Responses API websocket v2 mode

​
Deprecated and Removed Features

Some features have been deprecated or removed:

​
Deprecated

  • web_search_request - Use top-level web_search = "live" in config instead
  • web_search_cached - Use top-level web_search = "cached" in config instead

​
Removed

  • search_tool - Superseded by web search functionality
  • request_rule - Removed in favor of improved approval system
  • experimental_windows_sandbox - Removed
  • elevated_windows_sandbox - Removed
  • remote_models - Removed
  • steer - Now default behavior (Enter submits immediately)
  • collaboration_modes - Now always enabled

​
Feature Lifecycle

​
Stage Descriptions

1

Under Development

Feature is incomplete and not ready for users. Not shown in /experimental menu. Default: disabled.
2

Experimental

Feature is ready for testing. Available in /experimental menu. May have rough edges. Default: disabled.
3

Stable

Feature is production-ready. Can be toggled on/off as needed. Default: varies per feature.
4

Deprecated

Feature is being phased out. Use alternative approaches. May show warnings.
5

Removed

Feature no longer exists. Flag kept for backward compatibility only.

​
Configuration Precedence

When feature flags are specified in multiple places:
  1. --enable / --disable flags (highest priority)
  2. -c features.name=true overrides
  3. Profile [features] section
  4. Base config.toml [features] section
  5. Built-in defaults (lowest priority)

​
Suppress Unstable Feature Warning

If you enable under-development features, Codex will show a warning. To suppress it:
config.toml
suppress_unstable_features_warning = true

​
Examples

codex --enable js_repl --enable multi_agent --enable apps

Global Options

Learn about command-line options

Configuration

Configure features in config.toml