/agent

wiki / raw / openai-codex-repository-architecture-2026

OpenAI Codex Repository & Architecture Specification

updated 2026-08-27

Original source: https://github.com/openai/codex SHA256: 45788dafc27357bf9e9c323f46f57878d22dfb425b0373df899ea2284cfb7db5

OpenAI Codex Repository & Architecture Specification

Primary repository: openai/codex (Apache-2.0).

Codex CLI is OpenAI’s local and headless coding agent harness built as a multi-crate Rust workspace (codex-rs).

Multi-Crate Workspace Architecture

The workspace is structured into specialized crates implementing a clean separation of concerns across protocols, control planes, execution engines, and OS sandboxes:

  1. Frontends & Transports:

    • codex-cli: Command-line interface handling argument parsing, headless execution, and the /goal autonomous loop.
    • codex-tui: Terminal User Interface built with Ratatui/crossterm, managing asynchronous rendering, streaming tokens/diffs, and permission approvals.
    • codex-app-server & codex-app-server-protocol: JSON-RPC daemon and protocol enabling external clients (IDE extensions, desktop app, remote agents) to drive the Codex engine over Unix Domain Sockets (UDS) and WebSockets.

  2. Core Agent Engine:

    • codex-core: The central OODA (Observe-Orient-Decide-Act) turn state machine, prompt assembler, context fragment manager, and tool router.
    • codex-protocol: Pure domain contracts and schemas defining Thread, Turn, Message, ToolCall, ToolResult, and Diff.

  3. Execution Substrate & Sandboxing:

    • codex-sandboxing: Multi-platform sandbox isolation implementing OS-specific security boundaries:
      • Linux: Bubblewrap (bwrap) mount namespaces and Landlock LSM filesystem restrictions.
      • macOS: Apple Seatbelt (sandbox-exec) profile compilation.
      • Windows: Windows restricted security tokens and job objects.
    • unified_exec: Subprocess lifecycle manager, PTY allocation, head/tail stream buffer truncation (HeadTailBuffer) to prevent context window blowouts, and signal escalation.

  4. Tools & Protocols:

    • codex-mcp: Model Context Protocol (MCP) client connection manager, dynamic tool discovery, resource elicitation, and authentication handshakes.
    • apply-patch: Fine-tuned unified diff parser and patch engine optimized for OpenAI models.
    • codex-skills: Engine for loading and injecting procedural agent skills (SKILL.md).

  5. Persistence & Observability:

    • codex-thread-store: Thread lifecycle management, turn history persistence, rollbacks, and forks.
    • codex-agent-graph-store: Multi-agent hierarchical execution tracking.
    • codex-rollout & codex-rollout-trace: OpenTelemetry diagnostics and execution traces.