Building on the Codex Harness — Dominik Kundel, OpenAI
Dominik Kundel from OpenAI's Codex team explains the Codex App Server, the open-source JSON-RPC protocol that wraps the Codex harness and powers the Codex app, IDE extensions, and third-party clients. He covers live protocol events, more than 120 client messages, ChatGPT sign-in, developer instructions, deferred dynamic tools, shipping and binding generation, the Python SDK, and a demo of Codex running inside Doom.
Building on the Codex Harness Instead of Your Own
Dominik Kundel from OpenAI’s Codex developer experience team opens by polling the room: most attendees find building an agent harness intimidating. His core argument is that you don’t have to. Instead, build on the harness that already powers Codex, through the Codex App Server, an open-source JSON-RPC protocol that wraps the harness and is used by the Codex desktop app, the IDE extensions, and third-party clients such as Xcode and JetBrains IDEs. He notes that the app server even powers a Codex plugin inside Claude Code, which lets developers hand review or coding tasks to Codex from another agent.
What the App Server Is and How It Relates to ACP
Kundel frames the app server as a protocol layer similar in spirit to the Agent Client Protocol (ACP). Both let a client deeply integrate with an agent harness. The key difference he draws is control: ACP is a more generic protocol, while the app server exposes fine-grained control over the individual parts of the harness. Both the harness and the app server are Apache 2.0 licensed, so developers can fork them. The harness is not locked to OpenAI models either. It can be pointed at any model provider with a Responses API-compatible endpoint, and there are convenience settings for LM Studio and Ollama.
Seeing the Real Events
Rather than showing hypothetical messages, Kundel built an inspector that intercepts traffic between the real Codex app and the app server. The captured stream includes thread starts carrying configuration (which project is being worked on), configuration reads, new thread creation, and streamed delta messages carrying output. His point is that the protocol mirrors nearly everything the app does. Streaming, file search, and file system modifications all pass between app and server, so a custom client can use the same capabilities the first-party app uses.
Client Surface and Control
The protocol currently exposes more than 120 client messages, and Kundel says more are added regularly. They range from initialization, where clients configure app-specific behavior, to thread modifications and turns, which are the classic operations. They also include more app-specific functions, such as setting a goal (useful if you want to build your own goal mode), listing plugins, and direct file system access. Developers can therefore rebuild much of the Codex app experience in their own interface.
Authentication is another practical feature. Through the protocol, end users can sign in with ChatGPT and use their own subscription. Their usage then counts against their own Codex limits rather than the application developer’s account. Kundel cites tools like T3 Code as examples of this model.
Customizing the Agent
There are two main levers. The first is developer instructions. Kundel recommends appending to the Codex system prompt through developer instructions rather than replacing it. This keeps the prompt tuning OpenAI has done for each model while letting a product add its own behavior. The Codex app itself uses this mechanism for app-specific functionality that differs from the IDE extension or the CLI.
The second lever is dynamic tools. Developers can expose their own functions to the agent, either via MCP or by defining tools directly. Tools can be marked as deferred loading. Instead of injecting every tool definition into the system prompt and bloating the context window, Codex uses a tool search tool to discover deferred tools when needed. Kundel says this will be covered in more depth in a follow-up session.
Beyond these, configuration can be set per thread. Developers can change the model provider, choose a different model, or apply fine-grained sandbox controls such as which network connections are allowed and which files can be modified.
Shipping the Binary and Generating Bindings
The app server ships inside the Codex CLI as the same binary, so anyone with the CLI installed can start it. The Codex app bundles its own copy inside the application package, and that copy changes with each app release. On Windows, two binaries are shipped, one Linux-compiled for WSL mode and one native Windows build. Kundel stresses that the protocol changes between versions, so the recommended practice is to bundle a known binary with your own application. This gives full control over which capabilities you build against rather than relying on whatever version a user happens to have installed.
Codex can generate TypeScript bindings or a JSON schema for a specific app server version, which helps keep clients in sync with the protocol. The server can run over stdio or WebSockets, and he suggests asking Codex which transport suits your use case.
For integration there are two routes. The newly released Python SDK handles much of the lifecycle management and includes sign-in with ChatGPT support. Kundel also jokes that most of the audience at an AI engineering conference will simply ask Codex to build the integration. He says Codex is very good at implementing this protocol, usually needing only a pointer to the documentation. As a demonstration he mentions a Windows-native client that Codex produced almost in one shot, using Visual Basic.
Doom: Codex Inside a Game
The most playful section is a demo of Codex running inside Doom, the inverse of running Doom inside Codex. The setup is an Electron app built on Cloudflare’s Doom WASM renderer. Most of the engine is written in C, and the game uses FreeDoom assets. Kundel had Codex modify the game files, and the chat interface renders natively inside the game. Messages travel from the game through Electron’s IPC to the app server.
With dynamic tools, the agent can read and change in-game state, such as armor, health, weapons, and ammo. When asked for the current directory, Codex ran a shell command and reported back, which shows the agent has a real workspace on the machine. Kundel jokes that you could write code inside Doom, though he admits the Codex app is probably the better choice for that. The demo’s real point is that the app server is not tied to the chat interface and can drive any custom UI.
App Server Versus codex exec
Audience members often asked how the app server differs from codex exec. Kundel explains that codex exec is a non-interactive command for kicking off tasks. It suits scripting and CI/CD, such as auto-fixing a pull request. The app server is the better choice for comprehensive clients that display the agent’s activity, and especially for applications that run many Codex threads at once, such as a custom eval harness or features like goal mode. In those cases the app server provides full control over the harness and avoids the need to build your own parallelization across many exec calls.
Three Takeaways
Kundel closes with three recommendations. First, ship your own version of the harness. Relying on a user’s installed CLI exposes you to breaking changes, experimental features that may vary, and users who have not updated. Second, expose new functions as tools and mark them as deferred. This keeps the context window clean while keeping the tools available to the agent. Third, when customizing behavior, add developer instructions rather than writing a new system prompt. Harness prompts are tuned to stay in distribution for each model, and replacing them throws away that work and can degrade agent performance.
He closes by pointing attendees to the slides via a QR code and noting that he will be at the OpenAI booth for about fifteen minutes afterward for questions.