Codex CLI Architecture: A Map for the 90-Crate Rust Monorepo

OpenAI's Codex CLI is a terminal-based coding agent that reads your code, executes commands, applies patches, and talks to OpenAI models — all from your shell. But beneath that simple description lies a 90-crate Rust monorepo with a JavaScript distribution shim, dual build systems (Cargo + Bazel), and a busybox-style binary dispatch trick. This article provides the mental map you need to navigate the codebase without getting lost.

Repository Layout: Two Workspaces, One Product

The repository is organized around a clean separation between the Rust core and a thin JavaScript distribution layer:

Directory	Purpose
codex-rs/	Rust workspace — the actual product (~90 crates)
codex-cli/	npm shim — JavaScript wrapper for npm install distribution
sdk/	Client SDKs for programmatic access
docs/	User-facing documentation
scripts/	Build and release automation

The Rust workspace is defined in codex-rs/Cargo.toml, which lists all 90 member crates and pins the workspace to Rust edition 2024. The workspace uses the resolver v2 and enforces a strict set of Clippy lints across all crates — over 30 deny-level rules covering everything from unwrap_used to redundant_clone.

graph TD
    subgraph "Repository Root"
        A["codex-rs/"] -->|Cargo workspace| B["~90 Rust crates"]
        C["codex-cli/"] -->|npm package| D["JS shim + platform binaries"]
        E["MODULE.bazel"] -->|CI builds| F["Bazel build system"]
        G["justfile"] -->|Developer tasks| H["just runner"]
    end

Why both Cargo and Bazel? Cargo is the developer's daily driver. Bazel powers CI with hermetic, reproducible builds. The justfile bridges the gap with task runner commands that abstract over both.

Tip: If you change any Cargo.toml or Cargo.lock, run just bazel-lock-update from the repo root to keep MODULE.bazel.lock in sync. CI will catch drift, but it's faster to fix locally.

Crate Clusters: Grouping 90 Crates by Function

Ninety crates sounds overwhelming, but they fall into clear functional clusters. Here's the taxonomy:

graph LR
    subgraph Entry["Entry Points"]
        cli["cli"]
        tui["tui"]
        exec["exec"]
        appserver["app-server"]
        mcpserver["mcp-server"]
    end
    subgraph Core["Core Engine"]
        core["core"]
        protocol["protocol"]
        config["config"]
        features["features"]
    end
    subgraph Tools["Tool System"]
        tools["tools"]
        sandboxing["sandboxing"]
        applypatch["apply-patch"]
        shellcmd["shell-command"]
        hooks["hooks"]
    end
    subgraph Model["Model/API"]
        codexapi["codex-api"]
        modelsmgr["models-manager"]
        login["login"]
        backend["backend-client"]
    end
    subgraph Utils["~20+ Utilities"]
        utilsabs["absolute-path"]
        utilscache["cache"]
        utilspty["pty"]
        utilsmore["..."]
    end
    Entry --> Core
    Core --> Tools
    Core --> Model
    Tools --> Utils
    Model --> Utils

Cluster	Key Crates	Purpose
Entry Points	cli, tui, exec, app-server, mcp-server	Binary targets and interface layers
Core Engine	core, protocol, config, features	Session orchestration, SQ/EQ messaging, configuration
Tool System	tools, sandboxing, apply-patch, shell-command, hooks	Command execution, patching, sandboxing
Model/API	codex-api, models-manager, login, backend-client	HTTP/WebSocket transport, auth, model resolution
MCP	codex-mcp, rmcp-client, mcp-server	Model Context Protocol client and server
State/Persistence	state, rollout	SQLite state DB, session recording
Utilities	absolute-path, cache, pty, string, fuzzy-match, etc.	Shared helpers kept out of core

The core crate at codex-rs/core/src/lib.rs enforces #![deny(clippy::print_stdout, clippy::print_stderr)] — all user-visible output must go through the TUI or tracing stack, never raw println!. This pattern is replicated across library crates.

The MultitoolCli: One Binary, Many Modes

The primary entry point is codex-rs/cli/src/main.rs, which defines the MultitoolCli struct — a clap-based parser that routes to different execution modes:

#[derive(Debug, Parser)]
#[clap(
    subcommand_negates_reqs = true,
    bin_name = "codex",
)]
struct MultitoolCli {
    #[clap(flatten)]
    pub config_overrides: CliConfigOverrides,
    #[clap(flatten)]
    interactive: TuiCli,
    #[clap(subcommand)]
    subcommand: Option<Subcommand>,
}

The subcommand_negates_reqs = true attribute is key: when no subcommand is given, the default args (prompt, model, etc.) flow through to the interactive TUI. When a subcommand is present, those requirements are waived.

The Subcommand enum maps to the full surface area:

flowchart TD
    A["codex"] --> B{Subcommand?}
    B -->|None| C["Interactive TUI<br/>(codex-tui)"]
    B -->|exec| D["Headless execution<br/>(codex-exec)"]
    B -->|review| E["Code review mode"]
    B -->|login/logout| F["Auth management<br/>(codex-login)"]
    B -->|mcp| G["MCP server management"]
    B -->|mcp-server| H["Run as MCP server<br/>(codex-mcp-server)"]
    B -->|app-server| I["JSON-RPC IDE server<br/>(codex-app-server)"]
    B -->|sandbox| J["Sandboxed execution<br/>(seatbelt/landlock/windows)"]
    B -->|resume/fork| K["Session management"]
    B -->|apply| L["Apply last diff"]
    B -->|cloud| M["Cloud tasks"]

Each subcommand variant delegates to a different crate — Exec(ExecCli) routes to codex-exec, AppServer(AppServerCommand) routes to codex-app-server, and so on. The codex exec alias (visible_alias = "e") enables quick non-interactive runs: codex e "fix the failing tests".

Busybox-Style Dispatch: argv[0] Magic

One of the more clever patterns in the codebase is the busybox-style dispatch in codex-rs/arg0/src/lib.rs. The idea: ship a single binary, but when it's invoked via a symlink with a different name, dispatch to entirely different functionality.

flowchart TD
    A["Process starts"] --> B["Read argv[0]"]
    B --> C{Binary name?}
    C -->|"codex-linux-sandbox"| D["codex_linux_sandbox::run_main()<br/>(never returns)"]
    C -->|"apply_patch"| E["codex_apply_patch::main()"]
    C -->|"codex-execve-wrapper"| F["Shell escalation wrapper"]
    C -->|anything else| G["Check argv[1] for<br/>--codex-run-as-apply-patch"]
    G --> H["Load .env, build runtime,<br/>run main_fn()"]

The arg0_dispatch() function reads the executable name from argv[0], matching against constants like APPLY_PATCH_ARG0 ("apply_patch") and CODEX_LINUX_SANDBOX_ARG0. When the binary is invoked through a symlink named apply_patch, it runs patch application logic directly.

The prepend_path_entry_for_codex_aliases() function creates a temporary directory with symlinks to the current executable under these alias names, then prepends that directory to PATH. This means child processes — especially sandboxed ones — can find apply_patch on the PATH without shipping a separate binary. A file-locking janitor cleans up stale directories from previous sessions.

Tip: On Windows, symlinks don't work the same way, so the code generates .bat batch scripts instead that invoke the main binary with a special --codex-run-as-apply-patch flag. Check the #[cfg(windows)] blocks in prepend_path_entry_for_codex_aliases().

npm Distribution: The JavaScript Shim

Most developers install Codex via npm install -g @openai/codex. But the actual product is a native Rust binary — so how does npm distribution work?

The answer is codex-cli/bin/codex.js, a thin Node.js shim that:

1. Detects the current platform and architecture
2. Resolves the corresponding optional dependency package (@openai/codex-linux-x64, @openai/codex-darwin-arm64, etc.)
3. Spawns the native binary with stdio: "inherit"
4. Forwards signals (SIGINT, SIGTERM, SIGHUP) to the child
5. Mirrors the child's exit code

flowchart LR
    A["npm install -g @openai/codex"] --> B["Platform detection<br/>(linux/darwin/win32 × x64/arm64)"]
    B --> C["Resolve optional dep<br/>@openai/codex-{platform}-{arch}"]
    C --> D["Locate native binary<br/>vendor/{triple}/codex/codex"]
    D --> E["spawn() with stdio: inherit"]
    E --> F["Forward signals + exit code"]

The platform mapping table covers six target triples, from x86_64-unknown-linux-musl to aarch64-pc-windows-msvc. The shim also detects the package manager (npm vs. bun) to provide correct reinstall instructions when a platform package is missing.

The signal forwarding at the bottom of the file is worth noting: the shim uses async spawn() instead of spawnSync() specifically so Node.js can respond to signals while the native binary runs. This ensures Ctrl-C propagates cleanly through the Node.js wrapper to the Rust process.

Contributor Conventions from AGENTS.md

The AGENTS.md file is both a contributor guide and a set of architectural principles. Key decisions worth internalizing:

Resist adding to codex-core. The core crate has grown large over time and the team explicitly pushes back on adding more code to it. Before adding to core, consider whether an existing crate works or a new crate should be created.

Module size limits. Target modules under 500 lines of code (excluding tests). If a file exceeds ~800 LOC, add new functionality in a new module. This applies especially to high-touch files like tui/src/app.rs.

No raw stdout/stderr. Library crates use #![deny(clippy::print_stdout)]. All user output flows through the TUI or tracing.

Exhaustive matches. Prefer exhaustive match statements — avoid wildcard arms so the compiler catches new enum variants.

Dual build system. Changes to Cargo.toml/Cargo.lock require running just bazel-lock-update. Any use of include_str! or sqlx::migrate! needs corresponding Bazel BUILD.bazel updates.

The conversation→thread rename. The codebase is migrating from "conversation" terminology to "thread." You'll see deprecated type aliases like type ConversationManager = ThreadManager throughout. New code should use "thread" exclusively.

What's Next

With this mental map of the repository structure, you're equipped to find any crate, understand any import path, and navigate the codebase with confidence. In Part 2, we'll dive deep into the protocol that makes all these crates talk to each other: the SQ/EQ (Submission Queue / Event Queue) pattern that forms the backbone of Codex's message-passing architecture.