A maintainer-focused Codex CLI fork for context-efficient tool output, safer execution, stronger diagnostics, and more reliable long-running agent workflows.
Enhancements | Feature inventory | Engineering case study | Build | Upstream Codex
Important
This is an independent community fork maintained by Hamdani. It is based on OpenAI Codex, but it is not affiliated with, maintained by, or endorsed by OpenAI.
Agent reliability is often determined at the unglamorous edges: context-efficient tool output, subprocess cleanup, bounded retention, deterministic diagnostics, configuration integrity, and test behavior under restricted environments. Codex Enhanced explores those edges as a transparent patch layer over a pinned upstream release.
The fork carries an explicit patch ledger spanning the Rust CLI, core runtime, hooks, TUI, configuration, protocol, and maintainer tooling. Every enhancement maps to its implementation commit, affected area, and prescribed verification in enhancements.toml.
| Area | What changed | Engineering goal |
|---|---|---|
| Context efficiency | Adaptive 6K/8K tool-output budgets, repeated-diagnostic coalescing, ANSI cleanup, and key-error extraction | Spend model context on signal instead of terminal noise |
| Runtime hardening | Configuration guards, safer output processing, and runtime checks | Fail safely and make invalid state visible |
| Unified exec | File-backed complete output with bounded retention | Keep full evidence available outside the model-visible context |
| Hook execution | Bounded streams, timeouts, and process-tree termination | Prevent runaway hooks and orphaned processes |
| Local doctor | Deterministic preflight checks and redacted JSON reports | Detect blockers before an expensive agent turn |
| Session workflow | Pinning in the resume picker with snapshot coverage | Keep important work easy to find |
| Compaction | Selective retry for local compaction failures | Recover only when retry is safe and meaningful |
| Test infrastructure | Capability-aware test partitioning | Separate sandbox-safe tests from capability-sensitive tests |
| Provenance | Build provenance and source-parity reporting | Make the running binary auditable |
See FEATURES.md for the complete capability inventory and FORK.md for the design rationale, patch architecture, validation strategy, and maintenance model.
Prerequisites: Rust 1.95, Git, just, and the native build dependencies required by upstream Codex.
git clone https://github.com/dhanizael/codex.git
cd codex
git switch showcase
cd codex-rs
cargo build --release --locked -p codex-cli
install -Dm755 target/release/codex "$HOME/.local/bin/codex-enhanced"
codex-enhanced --version
codex-enhanced doctor --preflightFor fast development, prefer cargo check -p <crate> and focused just test -p <crate> runs. Reserve release builds for final validation because upstream's optimized profile includes expensive link-time optimization and debug information.
python3 scripts/enhancement_ledger.py check
python3 scripts/enhancement_ledger.py report --upstream-ref upstream/main
python3 -m unittest scripts/test_enhancement_ledger.pyThe ledger reports missing or unmanaged patch commits and highlights overlap with newer upstream changes.
The documentation below is retained from the upstream project. Its installers and package-manager commands install the official OpenAI distribution, not Codex Enhanced.
Codex CLI is a coding agent from OpenAI that runs locally on your computer.
If you want Codex in your code editor (VS Code, Cursor, Windsurf), install in your IDE.
If you want the desktop app experience, run
codex app or visit the Codex App page.
If you are looking for the cloud-based agent from OpenAI, Codex Web, go to chatgpt.com/codex.
Run the following on Mac or Linux to install Codex CLI:
curl -fsSL https://chatgpt.com/codex/install.sh | shRun the following on Windows to install Codex CLI:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"The standalone installers download from https://releases.openai.com/codex by default and fall back to GitHub Releases if a metadata or asset download is unavailable. To force GitHub Releases, set CODEX_INSTALLER_USE_RELEASES_OPENAI_COM to false (0 and no are also accepted):
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iexCodex CLI can also be installed via the following package managers:
# Install using npm
npm install -g @openai/codex# Install using Homebrew
brew install --cask codexThen simply run codex to get started.
You can also go to the latest GitHub Release and download the appropriate binary for your platform.
Each GitHub Release contains many executables, but in practice, you likely want one of these:
- macOS
- Apple Silicon/arm64:
codex-aarch64-apple-darwin.tar.gz - x86_64 (older Mac hardware):
codex-x86_64-apple-darwin.tar.gz
- Apple Silicon/arm64:
- Linux
- x86_64:
codex-x86_64-unknown-linux-musl.tar.gz - arm64:
codex-aarch64-unknown-linux-musl.tar.gz
- x86_64:
Each archive contains a single entry with the platform baked into the name (e.g., codex-x86_64-unknown-linux-musl), so you likely want to rename it to codex after extracting it.
Run codex and select Sign in with ChatGPT. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Business, Edu, or Enterprise plan. Learn more about what's included in your ChatGPT plan.
You can also use Codex with an API key, but this requires additional setup.
This repository is licensed under the Apache-2.0 License.