Introducing a new way to review your PRs.

Read the announcement

openai / codex

Lightweight coding agent that runs in your terminal

View on GitHub

13 documents · Updated Nov 16, 2026

overview

Knowledge Base updated: 2026-11-16

Knowledge Base Index

Orientation

This repository is the OpenAI Codex CLI monorepo. Its highest-level flow is: a user invokes codex, the CLI starts the TUI or another command mode, the core agent runtime talks to model/backend clients, and tool calls execute through policy-controlled sandbox layers while local state and history are persisted.

Main parts:

  • npm launcher (codex-cli/): published @openai/codex wrapper and binary handoff.
  • Rust workspace (codex-rs/): CLI, TUI, core agent runtime, tool execution, sandboxing, app server, extensions, clients, and local state.
  • SDKs (sdk/): TypeScript and Python SDK/runtime packages shipped with the repo.
  • Build and release infrastructure: Cargo, pnpm, Bazel, scripts, packaging, and repo-maintenance tooling.

Critical state lives primarily in local Codex home/config/auth stores, rollout/history/thread/state stores, extension/plugin storage, message-board collaboration stores, and external OpenAI/cloud/model-provider services reached through backend clients.

Architecture diagrams

flowchart LR
  User[User terminal]

  subgraph Packaging
    Npm[codex-cli npm package]
    Build[repo build and release scripts]
    SDK[SDK packages]
  end

  subgraph RustWorkspace[codex-rs workspace]
    CLI[cli entrypoints]
    TUI[tui interactive client]
    Core[core agent runtime]
    Config[config auth local state]
    Clients[backend and model clients]
    Exec[tool execution sandboxing]
    App[app-server and code-mode]
    Ext[extensions plugins capabilities]
    Collab[collaboration agents message-board]
  end

  subgraph External
    OpenAI[OpenAI/cloud/model services]
    OS[local shell filesystem sandbox]
  end

  User --> Npm --> CLI
  User --> CLI
  CLI --> TUI --> Core
  CLI --> App
  Core --> Config
  Core --> Clients --> OpenAI
  Core --> Exec --> OS
  Core --> Ext
  Ext --> Collab
  App --> Core
  SDK --> App
  Build --> Npm
  Build --> RustWorkspace
  Build --> SDK
sequenceDiagram
  participant U as User
  participant CLI as cli/arg0
  participant TUI as tui
  participant Core as core runtime
  participant Client as backend/model client
  participant Exec as exec/sandbox
  participant State as history/rollout/state

  U->>CLI: codex command
  CLI->>TUI: start interactive session
  TUI->>Core: submit prompt/input
  Core->>State: load context and history
  Core->>Client: request model response
  Client-->>Core: stream events/tool requests
  Core->>Exec: authorize and run tool call
  Exec-->>Core: output/status
  Core->>State: persist rollout/history
  Core-->>TUI: protocol events
  TUI-->>U: render transcript and status
flowchart TD
  Request[Tool request from core] --> Policy[execpolicy and approvals]
  Policy --> Shell[shell-command representation]
  Shell --> Server{exec-server?}
  Server -->|local| Sandbox[sandboxing facade]
  Server -->|server mode| ExecServer[exec-server protocol]
  ExecServer --> Sandbox
  Sandbox --> Linux[linux/bwrap/mxc sandbox]
  Sandbox --> Windows[windows sandbox service]
  Sandbox --> FS[file/search/patch helpers]
  Linux --> Result[streamed output]
  Windows --> Result
  FS --> Result
  Result --> Core[core protocol event]
flowchart LR
  AppClient[app-server client] --> Transport[app-server transport]
  Transport --> Daemon[app-server daemon]
  Daemon --> Protocol[app-server protocol]
  Protocol --> CodeMode[code-mode host/runtime]
  CodeMode --> AgentInstance[runtime agent instance]
  AgentInstance --> Core[core runtime]
  Core --> Exec[tool execution]
  Core --> Clients[backend/model clients]

Glossary

  • Codex home: Local filesystem area used by Codex for configuration, auth material, history, and state.
  • Rollout: The persisted trace/history representation of an agent conversation and its events.
  • Exec server: A separate execution service/protocol used to run tool commands outside the main CLI process when configured.
  • Code mode: App-server mediated runtime/host flow for embedding or driving Codex agent instances outside the plain terminal UI.
  • Message board: Collaboration substrate for agent identity, roles, queues/items, and guardian/reviewer flows.

Codebase-wide invariants

  • The primary Rust implementation is organized as a Cargo workspace rooted at codex-rs/Cargo.toml; workspace crates are listed as members and internal dependencies point at paths under codex-rs/**.
  • The JavaScript package workspace is declared in pnpm-workspace.yaml, with package roots including codex-cli, codex-rs/responses-api-proxy/npm, and sdk/typescript.
  • The published npm CLI package exposes the codex binary from codex-cli/package.json via bin.codex = bin/codex.js.
  • Top-level repo formatting and schema maintenance commands are centralized in package.json scripts, while Rust build/test/package behavior is also represented by codex-rs/Cargo.toml, Bazel files, and scripts/**.

Routing table