Skip to slide
079 / 170

CH 08 · Parallelism, the Responses API, and the App Server · 04/09

Read as one page

The App Server: one harness, many surfaces

Codex runs in a terminal, an IDE extension, a desktop app, and the web. They all share the same agent loop. The thing that lets them is the Codex App Server, a long-lived process that hosts the agent and speaks a JSON-RPC protocol over stdio (or WebSocket for remote). The "Unlocking the Codex harness" write-up explains the design.

The App Server exposes the harness through three conversation primitives, which are a genuinely good model for any agent protocol:

PrimitiveWhat it isLifecycle
ItemThe atomic unit of input or output (a user message, an agent message, a tool execution, an approval request, a diff)item/started -> item/*/delta (streaming) -> item/completed
TurnOne unit of agent work from a user input to the outputs for that inputbegins on submit, ends when the agent finishes
ThreadThe durable container for a whole session; holds many turns; can be created, resumed, forked, archivedpersisted so clients can reconnect

The protocol is bidirectional: the client sends a request to start a turn, the server streams back many notifications (item started, deltas, item completed), and the server can itself send a request back to the client when it needs an approval, pausing the turn until the client answers. This is exactly the approval flow from Chapter 7, expressed as a protocol.

Why build this instead of just exposing the agent as an MCP server (Chapter 10)? Because MCP, while great for calling an agent as a tool, did not cleanly express the rich, streaming, diff-emitting interaction an IDE needs. The App Server is the answer when you want the full harness as a stable, UI-friendly event stream. The cost is integration work (you write a JSON-RPC client in your language), but the payoff is one harness behind every surface, with backward compatibility so old clients can talk to new servers.

Finished this idea?

Your learning progress stays in this browser.