---
title: "OpenAI Codex Repository & Architecture Specification"
section: "raw"
type: "source"
created: "2026-08-27"
updated: "2026-08-27"
canonical: "https://pyweb.dev/wiki/raw/articles/openai-codex-repository-architecture-2026"
---
# OpenAI Codex Repository & Architecture Specification

Primary repository: [openai/codex](https://github.com/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.

---

## Agent Navigation

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt