Overview
OpenAI’s Codex CLI1 is an open-source, terminal-based coding agent that runs locally on your machine. Originally built in TypeScript with React/Ink for the terminal UI, the project underwent a major rewrite into Rust (now 94.9% of the codebase) using Ratatui for the TUI, Tokio for async execution, and a modular crate-based architecture. The CLI connects to OpenAI’s model APIs (or local providers like Ollama and LM Studio), interprets natural-language instructions, and autonomously executes multi-step coding tasks — reading files, writing patches, running shell commands, and managing MCP tool servers — all within a sandboxed environment with user-configurable approval policies.
Key Findings
- The architecture follows a client–server model internally: the
codex-corecrate acts as an in-process “app server” that manages sessions, conversation state, and model interactions, while thecodex-tuiandcodex-execcrates consume events as presentation layers2. - A three-tier sandbox system provides platform-specific isolation: macOS uses Apple’s Seatbelt (
sandbox-exec) profiles, Linux uses Bubblewrap + Landlock + seccomp, and Windows uses restricted tokens3. Each generates dynamic security policies based on filesystem and network access requirements. - The execution policy engine (
execpolicycrate) implements a rule-based system with prefix matching, network protocol rules, and pattern tokens to gate which commands can run without approval4. - An approval pipeline separates concerns into sandbox policies (what the OS enforces), execution policies (what the agent auto-approves), and Guardian assessments (risk classification with Low/Medium/High/Critical levels).
- The project supports headless execution via
codex execfor CI/CD pipelines, with JSONL event streaming, configurable approval policies, and non-interactive stdin processing. - MCP (Model Context Protocol) integration is bidirectional — Codex operates as both an MCP client (connecting to external tool servers) and experimentally as an MCP server (allowing other agents to use Codex as a tool)5.
- The 95+ crate workspace includes dedicated crates for analytics, PTY management, image processing, network proxying, keyring storage, and OpenTelemetry-based observability.
Footnotes
References
- OpenAI Codex CLI GitHub
- Codex Developer Documentation
- Model Context Protocol
- Ratatui TUI Framework
- Bubblewrap Sandbox
- Apple Seatbelt Documentation
Contents
| File | Description |
|---|---|
| architecture | Crate workspace, client-server model, session lifecycle, and turn orchestration |
| agent-loop | Model interaction, tool dispatch, conversation state, and multi-turn reasoning |
| sandbox | Platform-specific sandboxing: Seatbelt, Bubblewrap, Landlock, seccomp, and Windows |
| execution-policy | Approval pipeline, prefix rules, network policies, and Guardian risk assessment |
| terminal-ui | Ratatui TUI, event processing, session management, and headless exec mode |
| typescript-era | Original TypeScript/Ink implementation, approval system, config, and migration to Rust |