CH 08 · Parallelism, the Responses API, and the App Server · 04/09
Read as one pageThe 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:
| Primitive | What it is | Lifecycle |
|---|---|---|
| Item | The 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 |
| Turn | One unit of agent work from a user input to the outputs for that input | begins on submit, ends when the agent finishes |
| Thread | The durable container for a whole session; holds many turns; can be created, resumed, forked, archived | persisted 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.