Codex, Behind the Harness

When you send a message to Codex, what turns that request into an agent that can work on your project? The model is only one part of the path. The harness assembles context, exposes tools, manages execution, and carries state between interactions. Dominik Kundel’s walkthrough follows that path through the open-source Codex harness, written in Rust and licensed under Apache-2.0. You can study it, build on it, or fork it. This is the implementation snapshot presented in the recording; model releases can change both the APIs and the harness’s behavior.

Two protocols divide the journey. App-server handles communication between the user interface and the harness. The Responses API handles communication between the harness and model inference. That separation gives interface builders a way to use Codex’s agent machinery without implementing it themselves.

The Codex app itself uses app-server, so this is the interface to the product’s capabilities, not merely a demonstration endpoint. Kundel names T3 Code and RemoteX as community integrations, then describes using the same protocol to put Codex inside Claude Code through a plugin—and inside Doom. His previous day’s talk explored app-server in more depth; here, those examples establish how far the interface can vary while retaining the same harness.

On the inference side, Responses reworks the Chat Completions model for agent workflows, including built-in capabilities such as web search and image generation. Open Responses extends that idea into a shared specification, with participants including Ollama, LM Studio, and NVIDIA. Kundel describes the intended integration boundary as allowing Responses-compatible model providers to plug into Codex. The architectural distinction is useful: app-server connects interfaces to an agent; Responses connects that agent to inference.

Before inference begins, the harness constructs context. Three requirements shape that work:

• Size: unnecessary content consumes tokens and increases the opportunity for contradictory instructions or information.
• Flexibility: installing more skills, plugins, or MCP servers should not make the agent unwieldy.
• Cacheability: context construction should preserve opportunities to reduce latency and cost.

These requirements interact. A registry that conveniently exposes every capability can also become a large, changing part of every request.

Kundel makes the assembly visible with Nano Codex, a small TypeScript version of code from the public repository. Its model instructions are relatively stable and predictable. The available-skills list and tool registry are not: they grow as users install capabilities, particularly MCP tools. The harness therefore needs explicit policies for those variable parts of the prompt.

The first policy is deferred tool loading. In the walkthrough, deferred tools are described as being left out of the initial context and made available later through tool search. Kundel reports that the available-skills list is capped at 2% of the maximum context window, with descriptions progressively shortened when the list grows too large. These are distinct controls: one delays tool definitions until discovery; the other bounds the initial skill catalog.

Tool search is also available to custom harnesses through Responses, with support starting at GPT-5.4. The model can use the built-in search tool or a custom discovery implementation. One API distinction matters when implementing this today: deferred individual functions retain searchable names and descriptions while primarily deferring their parameter schemas. Deferral reduces what must be loaded up front; it does not require making a capability undiscoverable.

Once context is assembled, the agent needs to act. Kundel groups the next mechanisms into asynchronous work, computer use, and filesystem interactions. Asynchronous work matters when a delegated task should continue without blocking everything the main agent could do next.

In the interface described here, spawn_agent creates another agent instance and send_input supplies further content. The parent can wait for an agent or shut it down. A subagent is therefore a continuing interaction, not just a single function call that returns a finished answer. Background terminals use a similar lifecycle: start a process, send more input through stdin, and wait for a specified interval when its result is needed. The harness must manage the lifetime of work as well as its initial invocation.

The earlier Responses computer-use interface exposed one action at a time. A harness declared computer use and implemented the action types that interface supported. The newer approach described in the talk allows the agent to write code against a computer implementation, in a language such as JavaScript or Python. That moves more of the interaction logic into programs the agent can compose.

Kundel describes Codex browser use as Playwright-style JavaScript running in a persistent Node REPL. Variables and browser references survive across turns. In the Chromium demonstration, the first interaction obtains browser status and selects the relevant tab. Later interactions reuse those references to inspect information and perform actions, rather than reconstructing the browser connection each time.

The payoff is larger than retaining a variable. Once the agent understands one page’s structure, it can write a script that applies the same extraction to subsequent pages. For example, this JavaScript keeps a browser and tab alive, inspects the current page, then reuses the tab to collect headings from two related pages:

var { chromium } = await import("playwright");
var browser = await chromium.launch();
var tab = await browser.newPage();
await tab.goto("http://localhost:3000/docs/start");

// Inspect the page before choosing a reusable extraction.
var snapshot = {
  title: await tab.title(),
  headings: await tab.locator("h1, h2").allTextContents(),
};
console.log(snapshot);

// A later REPL turn can reuse the same tab and browser.
var pages = ["/docs/install", "/docs/configure"];
var results = [];
for (var path of pages) {
  await tab.goto(new URL(path, "http://localhost:3000").href);
  results.push({
    path,
    headings: await tab.locator("h1, h2").allTextContents(),
  });
}
console.log(results);

Here the local documentation pages are an illustrative application of the mechanism. Persistence carries the live objects across turns; scripting applies the learned page structure repeatedly.

Filesystem access combines specialized editing with general shell access. Kundel says models starting with GPT-5 were trained to edit and create files using apply_patch, expressing changes as diffs. Search and navigation go through a shell tool. The model’s tendency to reach for ripgrep also comes from training, so the harness supplies it when it is not already installed. On Windows, native PowerShell training lets the model use the platform’s shell directly. Tool design here follows interfaces the model has learned to use.

Those filesystem interactions pass through a sandbox layer whose implementation depends on the operating system:

The Windows implementation lives in the same Codex repository. Kundel points to David Wiesen’s Windows sandbox article for the alternatives considered and the reasons a custom implementation was necessary. The common harness boundary is enforced through different operating-system mechanisms.

Sandboxing introduces a practical problem: approval fatigue. A long task that repeatedly stops for permission can push users toward full-access mode, even when they understand the security objections. Better models do not remove that tension. Strong prompting to show initiative can still produce actions outside the user’s expectations.

Consider the example of an agent asked to email a file. If attaching it fails, an agent pushed to complete the task might upload the file to a sharing service instead. It has found a route to completion, but changed where the data goes. A separate failure mode is incorrect shell escaping that deletes more data than intended. Auto Review aims to reduce interruptions for legitimate actions while screening out dangerous behavior such as data exfiltration; it is a risk-reduction mechanism, not a deterministic security guarantee.

The deletion demonstration shows the review sequence:

1. Encounter the boundary. A proposed action, such as deleting a file, requires escalation beyond the sandbox.
2. Start an isolated reviewer. Auto Review runs as a separate subagent with read-only permissions and no ability to spawn more subagents.
3. Supply decision context. The reviewer receives guidance on authorization and risk taxonomies, the conversation transcript, and the proposed tool calls.

Read-only access lets the reviewer inspect the situation without performing the action under review.

The decision depends on what the user authorized as well as what the action would do. Deleting .git can be an explicitly requested operation; deleting it without that request can destroy project history the user expected to preserve. In the demonstrated file-deletion request, Kundel describes authorization as high because the user explicitly asked for the deletion. The review then considers the action’s impact and what disposition to assign. Authorization and impact are separate questions.

The same distinction applies to network access. Using curl against Google to check connectivity is materially different from uploading a file. Both involve the network, but the data movement and authorization differ. Kundel presents this as a simplified view of the engineering and research behind the system and directs readers to the Auto Review article for the fuller treatment.

An agent can make many tool calls, so faster token generation solves only part of its latency problem. Kundel reports that GPT-5.3-Codex-Spark ran on Cerebras at 1,000 tokens per second, making network overhead the bottleneck in the tool interactions he describes. That figure is generation throughput, not end-to-end task completion speed.

Responses WebSocket mode addresses this by maintaining a persistent connection instead of repeatedly using the HTTP/server-sent-events path. It also supports stateful context: after a tool call, the harness can send the new tool result rather than resending all the conversation items. Connection reuse reduces transport overhead; incremental input reduces the amount of repeated context sent over that connection.

The live demo server crashes, and Kundel switches to a backup to show the difference. In the backup illustration, the incremental path sends one item where the comparison path resends nine items. Repeated across a tool loop, that difference explains why transport becomes a worthwhile optimization once inference is fast. The demonstration does not report a measured end-to-end speedup.

The /goal mechanism adds a continuation policy around the agent’s work. Kundel demonstrates it with number guessing in a hosted demo that he describes as replayable after the talk. The objective is achieved only when the agent has guessed the number, giving the loop a concrete completion condition.

Until the objective is achieved, the harness injects a continuation prompt containing the goal. This keeps the original objective present as work continues. The loop stops when the model calls update_goal to report achievement. There are two responsibilities here: the harness supplies the continuation, while the model signals that the goal has been met.

That mechanism explains why a goal should be concrete and verifiable rather than an essay of instructions. A completion condition such as successfully guessing the number is easier to recognize than a broad aspiration with no clear stopping point. Once loops can keep an agent working for hours or days, however, continuation creates another requirement: managing the context accumulated along the way.

Kundel dates Codex’s adoption of automatic server-side compaction to the end of the previous year. He describes it as a model-trained operation intended to preserve performance as the agent continues. Compaction can be triggered manually or automatically: the previous context is replaced for subsequent turns by a new context containing a compaction item. Current documentation describes that item as opaque and encrypted, carrying forward key state. It is a context handoff, not a promise that every historical detail remains accessible or that every task’s performance is unchanged.

These mechanisms leave builders with two practical adoption paths. The open-source app-server and harness can be a blueprint to study or the foundation of another product. A custom harness can instead use Responses capabilities such as tool search, apply_patch, WebSockets, and server-side compaction. Kundel’s closing advice is to track model releases, Responses changes, and Codex changes together: as the model learns new interfaces and the API exposes new capabilities, the right harness design changes with them.