xCodex (xtreme-Codex)

xCodex (short for “xtreme-Codex”) is an independent fork of OpenAI’s Codex CLI.

• Repo: xCodex
• Binary: xcodex
• Upstream: https://github.com/openai/codex

xCodex is not affiliated with, endorsed by, or supported by OpenAI.

Status / stability

This is a fast-moving fork. Some features are experimental, may be incomplete, and can be temporarily broken. Expect rough edges, churn, and occasional behavior changes.

When filing issues, include repro steps and attach the files printed by /feedback.

Highlights

New in xCodex

• Context Control: Keep context under control with /compact and /autocompact (see the Context control guide).
• Agent Thoughts: Hide/show agent thoughts in the TUI with /thoughts (see the Thoughts guide).
• Git Worktrees: Switch a session between git worktrees with /worktree and manage shared dirs (see the Worktrees guide).
• ⚡Tools: Open ⚡Tools with Ctrl+O (or /xtreme) and customize the status bar with /settings (see the Settings guide).
• UI Theme: Customize the UI theme with /theme and $CODEX_HOME/themes (including themed syntax highlighting for code) (see the Theme guide and theme config reference).
• Transcript Rendering: Toggle transcript rendering features like diff highlighting, highlighting past prompts, and syntax highlighting for fenced code blocks (see the Settings guide).
• Hooks: Automate xcodex with three levels of hooks: external (spawn), Python Host “py-box” (persistent), and in-proc PyO3 (advanced) (start with the Hooks guide).
• Background Terminals: Manage background terminals with /ps (list) and /ps-kill (terminate) (see the Background terminals guide).
• MCP Servers: Inspect and manage MCP servers from inside the TUI with /mcp (including startup status, timings, and retry hints) (see the MCP config reference).
• Lazy MCP Loading: Speed up startup by deferring MCP server startup with lazy/manual modes (see the Lazy MCP loading guide and MCP integration config reference).
• Ignore Files: Keep sensitive paths out of AI context with ignore files (.aiexclude / .xcodexignore) and control exclusion behavior with /exclusion (see the Ignore files guide and Exclusion config reference).
• TUI2: TUI2 still lives :)

Fork-only docs

Fork-specific docs live in docs/xcodex/ (start at the xCodex docs index).

Roadmap

High-level roadmap (subject to change):

• v0.1.0 ✅: hooksv1
• v0.2.0 ✅: hooksv2, worktree v2
• v0.3.0 ✅: soft block + themes (highlight composer + diff highlight + ...)
• v0.3.1 ✅: fork health (feature inventory + E2E tests + merge prep)
• v0.3.5 ✅: resume/startup responsiveness + themed syntax highlighting + small QoL/bug fixes
• v0.3.6 ✅: TUI exclusion controls(/exclusion command), transcript rendering fixes, and GPT-5.3 Codex support
• v0.4.0 ✅: plan mode + split diff mode + approval-flow reliability + worktree/exclusion UX polish
• v0.5.0: observer-only sub-agents
• v0.6.0: infinite mode (built on /plan)
• v0.7.0: hooks expansion (beyond observer-only)
• v0.8.0: workflow + packaging (per-project profiles, runbooks/macros, approval policy profiles, multi-account)
• v0.9.0: UX/theming/integrations
• v1.0.0: stability milestone

Quickstart

This fork ships an npm distribution (recommended) and also supports building from source.

Install (npm)

npm i -g @eriz1818/xcodex
xcodex --version
xcodex

Prereleases are published under the alpha dist-tag:

npm i -g @eriz1818/xcodex@alpha

Install (build from source)

See docs/install.md for full requirements; the shortest path is:

# from repo root
cargo install just

# builds codex-rs and installs the CLI as `xcodex` (default: ~/.local/bin/xcodex)
cd codex-rs
just xcodex-install --release

# Default: local Bazel build (no BuildBuddy/remote cache).
# Opt into remote cache/BEP: just xcodex-install --release --remote
# Avoid all network fetches (requires deps already cached): just xcodex-install --release --offline

xcodex --version
xcodex

If you prefer not to use just, run:

scripts/install-xcodex.sh --release

Usage

See xcodex --help (or docs/getting-started.md).

Docs

Codex can access MCP servers. To configure them, refer to the config docs.

Large prompts (stdin / file)

For large prompts, avoid putting the prompt on the command line. Read it from a file or stdin instead:

xcodex --file PROMPT.md
cat PROMPT.md | xcodex

When using stdin, end input with EOF (Ctrl-D on macOS/Linux; Ctrl-Z then Enter on Windows).

Hooks (automation)

Hooks can receive event payloads containing metadata like cwd, and may include truncated tool output previews. Treat hook payloads/logs as potentially sensitive.

What xcodex supports

• Hooks (3 levels): external (spawn), Python Host “py-box” (persistent), and PyO3 (in-proc; separate build).
• Typed hook SDK installers: xcodex hooks install sdks <sdk> (Python/Rust/JavaScript/TypeScript/Go/Ruby/Java).

Performance (rough numbers)

Measured on macOS 26.2 (arm64), Python 3.11 (event: tool-call-finished, payload: 373 bytes):

cd codex-rs
PYO3_PYTHON=$(command -v python3.11) cargo run -p codex-core --bin hooks_perf --release --features pyo3-hooks -- --python $(command -v python3.11) --iters 20000 --warmup 2000 --external-iters 200 --markdown

• External hook (Python, per-event spawn): ~20.2ms/event (includes serde_json::to_string + json.loads)
• Out-of-proc host (Python, persistent): ~1.98µs/event (JSONL over stdin; includes serde_json::to_string + json.loads)
• In-proc baseline: ~0.33ns/iter (Rust loop only)
• In-proc PyO3: ~2.22µs/event (includes serde_json::to_string + json.loads + Python callable)

Start here:

• Hook configuration + supported events: docs/xcodex/hooks.md.
• External hooks (spawn-per-event): docs/xcodex/hooks-external.md.
• Typed hook SDKs + installers (Python/Rust/JS/TS/Go/Ruby/Java): docs/xcodex/hooks-sdks.md.
• Python Host hooks (long-lived “python box”): docs/xcodex/hooks-python-host.md.
• PyO3 hooks (in-process; separately built): docs/xcodex/hooks-pyo3.md.
• Copy/paste scripts: examples/hooks/ and docs/xcodex/hooks-gallery.md.
• CLI helpers: xcodex hooks help, xcodex hooks init, xcodex hooks install sdks list, xcodex hooks install samples list.

Configuration

Codex CLI supports a rich set of configuration options, with preferences stored in $CODEX_HOME/config.toml (default: ~/.xcodex/config.toml when invoked as xcodex). For full configuration options, see Configuration.

Execpolicy

See the Execpolicy quickstart to set up rules that govern what commands Codex can execute.

Docs & FAQ

• Getting started
  • CLI usage
  • Slash Commands
  • Running with a prompt as input
  • Example prompts
  • Custom prompts
  • Memory with AGENTS.md
• Configuration
  • Example config
• Sandbox & approvals
• Execpolicy quickstart
• Authentication
  • Auth methods
  • Login on a "Headless" machine
• Automating Codex
  • GitHub Action
  • TypeScript SDK
  • Non-interactive mode (xcodex exec)
• Advanced
  • Tracing / verbose logging
  • Model Context Protocol (MCP)
• Zero data retention (ZDR)
• Contributing
• Installing & building
• Open source fund

Support

For xCodex issues/bugs/feature requests, please use this repository’s issue tracker (not upstream).

License & attribution

This repository is licensed under the Apache-2.0 License.

See NOTICE for upstream attribution and third-party notices. OpenAI and Codex are trademarks of their respective owners.