`xCodex` (short for “xtreme-Codex”) is an independent fork of OpenAI’s Codex CLI.
npm install @eriz1818/xcodexxCodex (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.
---
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.
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).
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 + small feature + QoL/bug fixes + split diff mode
- 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
This fork ships an npm distribution (recommended) and also supports building from source.
``bash`
npm i -g @eriz1818/xcodex
xcodex --version
xcodex
Prereleases are published under the alpha dist-tag:
`bash`
npm i -g @eriz1818/xcodex@alpha
See docs/install.md for full requirements; the shortest path is:
`bashfrom repo root
cargo install just
(default: ~/.local/bin/xcodex)xcodex --version
xcodex
`
If you prefer not to use just, run:
`bash`
scripts/install-xcodex.sh --release
See xcodex --help (or docs/getting-started.md).
Codex can access MCP servers. To configure them, refer to the config docs.
For large prompts, avoid putting the prompt on the command line. Read it from a file or stdin instead:
`bash`
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 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 (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):
`bash`
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)serde_json::to_string
- Out-of-proc host (Python, persistent): ~1.98µs/event (JSONL over stdin; includes + json.loads)serde_json::to_string
- In-proc baseline: ~0.33ns/iter (Rust loop only)
- In-proc PyO3: ~2.22µs/event (includes + json.loads + Python callable)
Start here:
- Hook configuration + supported events: docs/xcodex/hooks.md.docs/xcodex/hooks-external.md
- External hooks (spawn-per-event): .docs/xcodex/hooks-sdks.md
- Typed hook SDKs + installers (Python/Rust/JS/TS/Go/Ruby/Java): .docs/xcodex/hooks-python-host.md
- Python Host hooks (long-lived “python box”): .docs/xcodex/hooks-pyo3.md
- PyO3 hooks (in-process; separately built): .examples/hooks/
- Copy/paste scripts: and docs/xcodex/hooks-gallery.md.xcodex hooks help
- CLI helpers: , xcodex hooks init, xcodex hooks install sdks list, xcodex hooks install samples list.
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.
See the Execpolicy quickstart to set up rules that govern what commands Codex can execute.
- 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
---
For xCodex` issues/bugs/feature requests, please use this repository’s issue tracker (not upstream).
---
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.