CodeVetter · Repo Unpack · System map
openai/codex
The repo is a pnpm/Bazel monorepo whose product lives in `codex-rs`. The `codex-cli` crate's `main.rs` dispatches subcommands into the TUI, non-interactive exec, MCP server, and app-server. `codex-core` owns the agent session, config, tools, models, and rollout persistence. `codex-app-server` exposes a JSON-RPC v2 API over stdio. Builds are Cargo via `just` plus Bazel CI. Storage is local files: `~/.codex/config.toml`, auth.json, and session rollout JSONL under `~/.codex/sessions`. External edges are the Responses/Chat Completions APIs, MCP servers, execve wrappers, and OS sandboxes (Seatbelt on macOS, bubblewrap/Landlock on Linux, restricted tokens on Windows).
- The published Node package `@openai/codex` is a launcher, not the agent. Its bin is `bin/codex.js`, which selects a native Rust binary by target triple and spawns it.
- The Rust CLI entrypoint is `codex-cli/src/main.rs`. `MultitoolCli` parses subcommands and `cli_main` matches `Tui`, `Exec`, `Mcp`, `AppServer`, `Resume`, `Fork`, `Review`, `Login`, `Sandbox`, and others before calling `arg0_dispatch_or_else`.
- Workspace membership and shared deps live in `codex-rs/Cargo.toml` (package version 0.0.0, edition 2024, resolver 3). Feature flags such as `vt100-tests`, `experimental-service-tier-flag`, and `login-server-sandbox` are declared on the workspace package.
- CI's blocking workflow `.github/workflows/blocking-ci.yml` runs fmt, package-manager pinning, a `cargo-shear` workspace check, and Bazel tests via `.github/actions/bazel-ci`. `bazel.yml` is the reusable workflow that sets `CARGO_BAZEL_REPIN` and calls `bazel test` with a target from `bazel-targets.txt`.
- Model traffic goes through `ModelClient` in `codex-rs/core/src/client.rs`, which selects Responses API vs Chat Completions from `WireApi` and retries with `max_retries`. Auth tokens come from `AuthManager` backed by `~/.codex/auth.json` (ChatGPT OAuth or API key).
- The app-server is a separate binary (`codex-app-server`) speaking JSON-RPC over stdio. `MessageProcessor` dispatches `thread/start`, `thread/resume`, `thread/fork`, `turn/start`, `turn/steer`, and `review/start` into `CodexMessageProcessor` and thread handlers.
- The interactive UI is the `codex-tui` crate. `tui/src/lib.rs` runs `App::run`, which owns the ratatui terminal, the `ChatWidget`, and a `FrameRequester`. Styling rules are documented in `codex-rs/tui/styles.md` and enforced by AGENTS.md.
- Sandboxing is platform-split. macOS uses Seatbelt profiles from `codex-rs/sandboxing/src/seatbelt.rs`; Linux uses bubblewrap plus Landlock (`codex-rs/linux-sandbox` and `codex-rs/sandboxing`); Windows uses a restricted token helper. Policy selection is `SandboxPolicy` (`read-only`, `workspace-write`, `danger-full-access`) resolved in `core/src/sandboxing/mod.rs`.
- The TypeScript SDK (`sdk/typescript`) is a thin client of the app-server protocol. `Codex` spawns the CLI with `app-server --stdio`, speaks JSON-RPC, and exposes `startThread`, `resumeThread`, and `Thread.run`. A Python SDK lives under `sdk/python`.