Inside the Codex harness: building the App Server

If you build developer tools, editors, or custom workflows and want to bring an AI coding agent directly into your own application, the Codex App Server is worth a close look. In this tutorial, you will learn what the Codex App Server is, how its bidirectional JSON-RPC API works, and how to get started embedding the Codex agent so you can stream progress, handle tool use, manage approvals, and display diffs inside your own interface.

What the Codex App Server Is

The Codex App Server is a layer that exposes the Codex agent through a bidirectional JSON-RPC API. In plain terms, that means your application and the Codex agent can talk to each other in both directions over a structured, request-and-response protocol. Instead of treating the agent as a one-shot "send a prompt, get an answer" service, the App Server lets your app maintain an ongoing conversation with the agent.

Why does bidirectionality matter? Because real coding agents do more than answer questions. They read files, run commands, propose edits, and ask for permission before doing anything risky. A simple request-response model struggles with that back-and-forth. A bidirectional JSON-RPC connection handles it naturally: your app sends instructions and questions to the agent, while the agent streams updates, tool calls, and approval requests back to you as work unfolds.

The App Server is designed for embedding. Rather than forcing users into a terminal or a separate chat window, you can surface the agent's capabilities inside the tool they already use — whether that is a code editor, an IDE plugin, a review dashboard, or something more custom.

The Core Capabilities You Get

Four capabilities define what the App Server gives you as an integrator.

Streaming progress. Long coding tasks do not finish instantly. The App Server streams progress events to your application as the agent works, so you can show users a live view of what is happening — which files are being examined, what step the agent is on, and when a task completes. This turns a black-box wait into a transparent, watchable process.

Tool use. The Codex agent relies on tools to do real work: reading and writing files, running shell commands, searching the codebase, and so on. Through the App Server, tool activity is visible to your application. You can observe which tools the agent invokes and reflect that in your UI, which is essential for building trust with users.

Approvals. Some actions an agent takes deserve a human check before they happen. The approval flow lets the agent pause and ask your application for permission — for example, before running a command with side effects. Your app presents the request to the user, collects a decision, and sends the answer back to the agent. This keeps humans in the loop without breaking the agent's workflow.

Diffs. When the agent proposes changes to code, the App Server surfaces those changes as diffs. That means your application can display proposed edits in the familiar before-and-after format developers expect, let users review them, and then accept or reject them.

How the JSON-RPC Flow Works

The exact message names and parameters are documented in the official Codex documentation, and you should rely on that for precise schemas — but the overall shape of the interaction is straightforward and worth understanding before you write any code.

1. Start the server. Your application launches or connects to the Codex App Server as a local process. Because it is a server, the details of how the agent runs stay hidden behind a stable interface.

1. Open a JSON-RPC session. Communication happens over the JSON-RPC protocol. Requests flow from your app to the server, responses come back, and — crucially — notifications stream from the server to your app without an explicit request each time. That's the bidirectional part.

1. Send a task or conversation turn. Your application submits a user request, such as "fix the failing test in auth.ts" or "refactor this module," along with the working context the agent needs.

1. Receive streamed events. As the agent works, your app receives a sequence of events: progress updates, tool invocations, and occasionally approval requests that require a decision.

1. Handle approvals. When an approval request arrives, your application surfaces it to the user (or applies your own policy), then sends the approval or rejection back through the connection.

1. Collect diffs and results. When the agent proposes edits, your app receives diffs it can render. Once a task finishes, the final result arrives and the session can continue with the next request.

Because the protocol is JSON-RPC, you do not need exotic dependencies. Most languages have mature JSON-RPC client and server libraries, and the message format is human-readable, which makes debugging much easier.

Getting Started: A Practical Path

If you are planning an integration, here is a sensible order of work.

1. Read the official Codex documentation first. The precise method names, event types, and parameter schemas live there, and they are the source of truth. Protocol details evolve, so build against the documented version rather than assumptions.

1. Prototype in a terminal or simple script. Before wiring the agent into a full UI, connect to the App Server from a minimal client. Send one simple task, print every event you receive, and study the flow. Seeing the raw event sequence — progress, tool use, approvals, diffs — teaches you the protocol faster than any summary can.

1. Build your approval UX early. Approvals are the part most likely to surprise you. Decide up front how your app will present permission requests: as blocking modal dialogs, as inline prompts, or through configurable policies for trusted operations. A good approval experience is the difference between an agent users trust and one they disable.

1. Render diffs natively. If your product already shows code changes, pipe the agent's diffs into that existing component. Users should review AI-proposed edits with the same tools they use for human reviews.

1. Plan for streaming in your UI. Design your interface around a stream of events rather than a single result. Show a live activity log or status area so users always know what the agent is doing.

Common Mistakes

• Treating the API as request-response only. The value of the App Server is the bidirectional stream. If you only wait for a final answer and ignore intermediate events, you lose progress reporting, approval handling, and diff visibility.

• Auto-approving everything for convenience. Skipping the approval flow for tool calls that modify files or run commands removes the safety net. Build approvals in from day one, even if you later add policy-based shortcuts.

• Hard-coding message schemas from memory. Protocol details can change between versions. Generate or validate your message handling against the official documentation rather than copied sample code.

• Ignoring diffs in the UI. Showing only "the agent made changes" without displaying the actual diff forces users to trust blindly. Always render proposed edits.

• Skipping the raw-event prototype. Jumping straight into full UI integration makes debugging painful. Spend an hour printing raw JSON-RPC traffic first — it will save you days.

• Assuming the agent always succeeds. Tasks can fail, stall, or finish in unexpected states. Handle error and cancellation paths in your UI as deliberately as the happy path.