# System map — openai/codex

> Canonical page: https://codevetter.com/unpack/codex/system-map

# System map — openai/codex

Scanned commit a1f40f3f1326eff7c81b860a4f4e27c1be186e10 (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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. — [codex-cli/package.json](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-cli/package.json) [codex-cli/bin/codex.js](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-cli/bin/codex.js)
- 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`. — [codex-rs/cli/src/main.rs#L1-L120](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/cli/src/main.rs#L1-L120) [codex-rs/cli/src/main.rs#L400-L750](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/cli/src/main.rs#L400-L750)
- 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. — [codex-rs/Cargo.toml#L1-L80](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/Cargo.toml#L1-L80) [codex-rs/Cargo.toml#L90-L250](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/Cargo.toml#L90-L250)
- 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`. — [.github/workflows/blocking-ci.yml](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/.github/workflows/blocking-ci.yml) [.github/workflows/bazel.yml](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/.github/workflows/bazel.yml)
- 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). — [codex-rs/core/src/client.rs#L1-L160](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/core/src/client.rs#L1-L160) [codex-rs/login/src/auth/manager.rs](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/login/src/auth/manager.rs) [docs/authentication.md](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/docs/authentication.md)
- 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. — [codex-rs/app-server/src/lib.rs#L1-L120](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/app-server/src/lib.rs#L1-L120) [codex-rs/app-server/README.md](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/app-server/README.md) [codex-rs/app-server-protocol/src/protocol/common.rs](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/app-server-protocol/src/protocol/common.rs)
- 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. — [codex-rs/tui/src/lib.rs#L1-L80](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/tui/src/lib.rs#L1-L80) [codex-rs/tui/src/app.rs](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/tui/src/app.rs) [codex-rs/tui/styles.md](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/tui/styles.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`. — [codex-rs/sandboxing/src/seatbelt.rs](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/sandboxing/src/seatbelt.rs) [codex-rs/core/src/sandboxing/mod.rs](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/codex-rs/core/src/sandboxing/mod.rs) [docs/sandbox.md](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/docs/sandbox.md)
- 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`. — [sdk/typescript/src/codex.ts](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/sdk/typescript/src/codex.ts) [sdk/typescript/README.md](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/sdk/typescript/README.md) [sdk/python/pyproject.toml](https://github.com/openai/codex/blob/a1f40f3f1326eff7c81b860a4f4e27c1be186e10/sdk/python/pyproject.toml)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)