Codex Harness (OpenAI)

Codex is OpenAI's coding agent — a model (the GPT‑5.x‑Codex line) wrapped in a Rust harness (codex-rs) that runs the same pure-library core across the CLI, IDE extension, cloud, and SDK. Its defining choices are an OS‑level sandbox, a stateless Responses‑API loop with client-side compaction, and AGENTS.md as a portable context map.

The harness is open source (github.com/openai/codex, Apache‑2.0). codex-rs/core is a UI‑agnostic library that talks to every surface over async channels and an event protocol, so the Codex CLI, VS Code/Cursor extension, web/cloud (chatgpt.com/codex), desktop app, and the TS/Python SDKs all reuse one engine. Source: openai/codex repo The model side is covered separately in GPT-5-Codex; this page is the harness.

The agent loop

Codex runs a Session → Task → Turn model over a dual queue: a Submission Queue carries operations in, an Event Queue streams events out, which keeps the UI async (you can type or interrupt while a tool call runs). A submission_loop persists until shutdown; Op::UserTurn starts a Task (one per session). A Turn builds the prompt (history + tools), streams the Responses API, executes any function_call, appends the output, and re-queries until the model emits a plain message; an empty Turn ends the Task. Independent tool calls run concurrently. Source: codex-rs protocol_v1.md The primary output is the diff on disk, not chat text.

Subagents

Codex subagents make the nested-loop model explicit in the app and CLI: the main agent can spin up specialized agents so the main context window stays cleaner, different parts of a task can run in parallel, and the operator can steer individual agents while work unfolds. The launch self-thread says the feature is available to all developers in the Codex app and Codex CLI. Source: X/@OpenAIDevs, 2026-03-16

The reviewed visual artifact shows the desktop app with a task titled "Spawn 3 fast subagents," a prompt to explore the OSS Codex repo, and the familiar Codex controls for handoff, commit, branch, local/full-access mode, and model/effort selection. The important routing implication is that Codex is no longer only a single-threaded harness: use subagents for scoped reconnaissance, parallel implementation/review, or source exploration, then require the main agent to merge evidence and run the final verification. Source: X/@OpenAIDevs visual artifact, 2026-03-16

Current source snapshot as of 2026-06-30: openai/codex default-branch HEAD 020828170fb2224f0d7a7a243a1f7d21cc3df5ee, Apache-2.0, about 94.6K GitHub stars. Source: GitHub API + git ls-remote, 2026-06-30

Context and memory

• AGENTS.md as a map, not a manual. OpenAI's own harness experiment rejected one giant file for a ~100-line table-of-contents AGENTS.md pointing into a versioned docs/ system of record, enforced by linters + a recurring "doc-gardening" agent — progressive disclosure over a context dump. Source: OpenAI "Harness Engineering"
• Loading: AGENTS.md is embedded into the first turn up to project_doc_max_bytes (default 32 KiB), discovered by walking up to a project root.
• Stateless + compaction: every request sends the full history (no previous_response_id) for provider portability and ZDR-friendliness; a context manager pairs tool calls with outputs, truncates oversized payloads, and compresses history into a recoverable summary item. Source: codex-rs core
• Kevin's Codex preset: config/codex/AGENTS.md tells Codex to search qmd first, use Graphify through project repo-graph blocks for repo topology, treat Hindsight/Honcho as runtime/profile memory until writeback, and use agent-browser for browser work with Playwright reserved for committed tests. Source: User request, 2026-07-04

Config, sandbox, tools

• ~/.codex/: config.toml (+ project .codex/config.toml, org requirements.toml), profiles, skills/<name>/SKILL.md, automations/<slug>/automation.toml, SQLite session/state stores, auth.json. Model + model_reasoning_effort (minimal…xhigh) and approval policy are config. Source: Codex config docs
• OS-level sandbox (the key safety choice — prevention, not just verification): read-only / workspace-write (network off by default) / danger-full-access, enforced by Apple Seatbelt on macOS and Landlock + seccomp on Linux. Approval policies (untrusted / on-request / never / granular) gate escalation. Source: codex-rs sandbox docs
• MCP: Codex is an MCP client (stdio + Streamable HTTP, OAuth) and also exposes an App Server (Thread/Turn/Item protocol over stdio/HTTP) so any language can build a Codex client — an alternative to MCP for embedding. See MCP Server Architecture. Source: Codex MCP docs
• Cloud + scheduling: background parallel tasks in hosted environments, @codex on GitHub PRs/issues, and (in Kevin's setup) a native scheduler storing automations in ~/.codex/sqlite/ mirrored to automation.toml. Source: Codex cloud docs

Contrast with the others

| | Codex | Claude Code | Cursor | |--|-------|-------------|--------| | Core | Rust pure library, 6 surfaces | TypeScript/Node CLI | IDE + harness-tuned model | | Safety | Kernel sandbox (Seatbelt/Landlock) | Post-edit hooks (verify after) | Local checkpoints + cloud VMs | | Context | full history + compaction | 3-layer memory (index/topics/transcripts) | persistent embeddings index | | Context file | AGENTS.md | CLAUDE.md | .cursor/rules + AGENTS.md |

Codex bets on OS-level prevention and a portable Rust core; Claude Code Harness bets on result-verification hooks; Cursor Harness bets on a managed embeddings index and a co-designed model. All three reduce to the same minimal turn loop (Harness Engineering). Kevin runs Codex for background automations and source-compile jobs in his Agent Operating System.

---

Timeline

• 2026-06-30 | Deep-reviewed the Codex subagents bookmark and local thumbnail artifact. Added subagents as a first-class Codex harness capability: parallel scoped workers with a main-agent merge/verification loop, available in the Codex app and CLI. Source snapshot: openai/codex HEAD 020828170fb2224f0d7a7a243a1f7d21cc3df5ee, Apache-2.0, ~94.6K stars. Source: X/@OpenAIDevs, 2026-03-16; Source: GitHub, 2026-06-30
• 2026-06-12 | Vercel AI SDK 7 HarnessAgent adds Codex as a swappable harness adapter with sandboxed sessions. See AI SDK HarnessAgent. Source: Vercel changelog, 2026-06-12
• 2026-06-02 | Page created from the openai/codex repo (codex-rs), official Codex docs, and OpenAI's "Harness Engineering" post. Captured the Rust shared-core, the SQ/EQ Session→Task→Turn loop, the stateless Responses-API + compaction model, AGENTS.md-as-map, the OS-level sandbox (Seatbelt / Landlock+seccomp), MCP + App Server, and cloud/scheduling. Source: openai/codex