← All posts

Explainer

The Codex harness is open: what OpenAI actually handed you

On August 20, 2026, OpenAI declared the engine under Codex a platform and put the whole thing on the table under Apache-2.0 — the harness that runs the agent loop, plus three ways in: codex exec for scripts and CI, the official Codex SDK for application code, and app-server, the JSON-RPC protocol the IDE extensions are built on. The sales pitch is one number: with harness changes alone — retained reasoning and context compaction, same GPT-5.6 Sol underneath — the ARC-AGI-3 score went from 13.3% to 38.3% while output tokens dropped sixfold (OpenAI-reported). The strategic read writes itself: if the harness moves a benchmark 3x without touching the model, the harness is worth open-sourcing precisely because the models are not.

What actually shipped — and what was already there

Get the timeline right first, because much of the coverage compresses it. The openai/codex repo was created on April 13, 2025 and has carried an Apache-2.0 license the whole time; the Rust core (codex-rs), the CLI, and the app-server source were already in it, and OpenAI published an engineering deep-dive on the App Server back in February 2026. So August 20 was not a source drop. It was a support contract: the app-server protocol is now documented for third parties, the TypeScript and Python SDKs are official, and OpenAI is explicitly inviting you to build products on the layer that was previously "read the code and good luck." The repo sits at roughly 114k stars as of this writing.

If you already run Codex CLI day to day, nothing about your binary changed — you were running the harness all along, and installation is the same. What changed is that the parts you could previously only read are now parts you are supported in building on.

Why the harness matters more than the model

The ARC-AGI-3 experiment is the most interesting artifact in the announcement. Two harness features — retained reasoning across turns and context compaction — took the same GPT-5.6 Sol model from 13.3% to 38.3% while cutting output tokens six times over. That is not a model release; it is plumbing. OpenAI-reported, single benchmark, so hold it loosely — but the direction matches what anyone operating long agent runs already knows: agents fail less from model stupidity than from context falling apart at hour two.

The post defines the category cleanly: the model answers, but "the surrounding execution system is the harness" — the thing that lets an agent understand a task, maintain context over time, inspect relevant information, call tools, expose progress, handle failures, request human approval when necessary, and return a useful result. Every serious agent product ends up rebuilding that list. OpenAI is betting that if its rebuild is free and good, you will bring your workloads — and your model spend — to it.

app-server: the piece worth reading

App-server is the harness exposed as a long-lived process speaking bidirectional JSON-RPC 2.0 messages (with the jsonrpc header omitted on the wire), newline-delimited JSON over stdio by default, with experimental WebSocket and Unix-socket transports. The API is organized around three primitives: threads (a conversation, which can be created, resumed, forked, and archived with persisted history), turns (one user-to-agent exchange), and items (the persisted inputs and outputs — user messages, agent reasoning, shell commands, file edits). A mandatory initialize handshake opens each connection, and the server can initiate approval requests that pause execution until a client answers.

This protocol was not designed for the announcement; it fell out of building the VS Code extension, which is its first production client. That is exactly why it is credible — the GitHub and JetBrains integrations ride the same events you would. If you have wired up Codex CLI notifications, app-server is the grown-up version of the same idea: instead of scraping one notify event, you subscribe to the full stream.

codex exec and the SDK: the automation surfaces

codex exec runs a bounded agent workflow without the TUI: final agent message to stdout, progress to stderr, --json for the full JSONL event stream, and --output-schema to force the result into a JSON Schema you define. The sandbox defaults to read-only — escalation to workspace-write is a flag, and the sandbox modes apply unchanged. Sessions resume with codex exec resume --last, which makes multi-stage pipelines practical. If you are putting an agent into CI, this is the entry point — running a coding agent in CI covers the pattern.

The SDK (TypeScript and Python, in the repo’s sdk/ directory) is the programmatic wrapper: start, resume, and stream Codex tasks from application code without speaking JSON-RPC yourself. OpenAI’s own framing of the split: the SDK simplifies common workflows; app-server gives product teams direct control over lifecycle and UX.

Can you point it at another model?

Yes — with one hard constraint. Custom providers go in config.toml:

[model_providers.myproxy]
name = "My Provider"
base_url = "https://api.example.com/v1"
env_key = "MYPROXY_API_KEY"
wire_api = "responses"

The constraint is that last line: per the config reference, "responses" is the only supported wire_api value — the endpoint must speak the OpenAI Responses API, not Chat Completions. Ollama and LM Studio ship as built-in providers (an --oss flag selects your configured local one), which is how you run open-weight models — gpt-oss included — under the open harness with zero API spend. Anthropic and other vendors’ native APIs need a Responses-compatible proxy in front. So: model-agnostic plumbing, Responses-shaped socket.

Harness vs Claude Agent SDK

The obvious comparison is Anthropic’s Claude Agent SDK, which has owned the "build your own agent on our engine" category since late 2025.

Anthropic’s stack is more turnkey today — hooks and subagents are mature, and the docs assume product builders. OpenAI’s counter is structural: you can read every line of the harness, ship it commercially, and swap the model endpoint, none of which the Claude side permits. For the day-to-day CLI matchup, see Claude Code vs Codex. Note the last row of that table: both stacks raise approval requests, and neither watches them for you.

What people are building on it

OpenAI’s examples are deliberately not coding tools: security investigation queues, support consoles, operations dashboards — "software that reflects how a specific person or team already works." Two named deployments, both OpenAI-reported: Cisco built App Builder inside Cisco Cloud Control on the Codex SDK, and Thrive Holdings’ accounting firm Crete ran a tax-preparation pilot that processed 7,000 returns with roughly a one-third reduction in preparation time. The shape of both is the same: the harness supplies the loop, the tools, and the approval gates; the builder supplies the domain and the UI.

What still ties you to OpenAI

• The models. The harness is open; GPT-5.6 Sol and the Codex model line are not, and the 38.3% headline was produced with them. Open harness plus open weights is a real configuration (gpt-oss over Ollama), but it is not the configuration the benchmark numbers describe.
• The wire format. Responses API only. Any non-OpenAI vendor needs a translation layer you operate.
• The services. ChatGPT-plan sign-in authenticates against OpenAI only; Codex cloud tasks and the compliance-logging integration are OpenAI infrastructure, not part of the Apache tarball.
• The numbers. ARC-AGI-3, the sixfold token cut, and both enterprise case studies are vendor-reported. Nothing here has independent replication yet.

Frequently asked questions

Where Backgrind fits

Backgrind is not a harness and does not compete with one. It is a desktop overlay for macOS and Windows that PTY-wraps whatever CLI you already run — codex today, and anything you build on the open harness tomorrow, because a terminal is a terminal — and floats it above your other windows, including games in borderless fullscreen. When the harness raises one of those approval requests, Backgrind pings you; you approve from a toast, a hotkey, or your phone, without alt-tabbing into a terminal you were supposed to be watching.

This release is the clearest evidence yet for the thesis Backgrind is built on: agent engines are commoditizing — the loop, the tools, the approval plumbing are now a free Apache-2.0 download from the biggest lab in the industry. What stays scarce is the other side of that approval request: a human who notices, in time, across three concurrent runs, while doing something else. That supervision layer is the overlay’s whole job, and it works the same whether the harness underneath is OpenAI’s, Anthropic’s, or yours.

Sources

Primary: Codex as a platform: build on the open agent harness (OpenAI Developers blog — components, harness definition, ARC-AGI-3 figures, Cisco and Thrive/Crete cases) and Unlocking the Codex harness: how we built the App Server (OpenAI engineering post on the protocol’s origin). Source, license and components: openai/codex (Apache-2.0; repo creation date and star count read from the GitHub API) and the app-server README (JSON-RPC framing, transports, threads/turns/items, initialize handshake). Custom providers and wire format: Codex config reference; non-interactive flags: codex exec docs. Claude side of the comparison: Claude Agent SDK overview and the license terms in anthropics/claude-agent-sdk-typescript. Release-date confirmation from secondary coverage: Open Source For You. ARC-AGI-3, the token figures, and both enterprise case studies are OpenAI-reported and not independently replicated.