# App Server Protocol for Codex Plugin Communication: JSON-RPC Architecture Explained

> Understand the app server protocol for Codex plugin communication. Learn how JSON-RPC and typed method calls enable seamless interaction and asynchronous updates.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: architecture
- Published: 2026-08-02

---

**The Codex plugin communicates with the local Codex App Server via a lightweight JSON-RPC-style protocol over HTTP, using typed method calls defined in [`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts) to execute operations like `thread/start` and `review/start` while receiving asynchronous updates through server notifications.**

The `openai/codex-plugin-cc` repository implements a structured communication layer between the Claude Code interface and the local Codex App Server. Understanding the app server protocol for Codex plugin communication is essential for developers building custom automations or extending the plugin's functionality beyond standard UI interactions.

## Protocol Architecture and Transport Layer

The protocol follows a **JSON-RPC 2.0** structure over standard HTTP transport. All requests target the local Codex App Server process, which exposes an endpoint at `localhost:8080` by default.

Each interaction consists of a POST request containing a JSON body that specifies the method name and parameters. The server responds with a JSON payload containing either the typed result or a structured error object. This synchronous request-response pattern handles initialization, thread management, and review operations, while a separate notification channel delivers asynchronous updates from server to client.

## Core Method Definitions in app-server-protocol.d.ts

The complete RPC contract resides in **[`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts)**, which exports the `AppServerMethodMap` interface. This type-safe mapping ensures compile-time verification of request and response shapes across nine primary methods.

The protocol exposes the following method signatures:

- **`initialize`** – Accepts `InitializeParams` and returns `InitializeResponse` to establish client capabilities and server readiness.
- **`externalAgentConfig/import`** – Uses `ExternalAgentConfigImportParams` to import external agent configurations.
- **`thread/start`** – Creates new conversation threads using `ThreadStartParams` (a trimmed variant omitting `persistExtendedHistory`) and returns `ThreadStartResponse`.
- **`thread/resume`** – Restores existing threads via `ThreadResumeParams` (also trimmed) yielding `ThreadResumeResponse`.
- **`thread/name/set`** – Renames threads through `ThreadSetNameParams` and returns `ThreadSetNameResponse`.
- **`thread/list`** – Retrieves active threads using `ThreadListParams`.
- **`review/start`** – Initiates code reviews with `ReviewStartParams`, returning a job identifier in `ReviewStartResponse`.
- **`turn/start`** – Begins new conversation turns via `TurnStartParams`.
- **`turn/interrupt`** – Cancels ongoing turns via `TurnInterruptParams`.

## Handling Asynchronous Server Notifications

Beyond synchronous RPC calls, the protocol supports **server-to-client notifications** defined by the `ServerNotification` type (aliased as `AppServerNotification`). These asynchronous messages enable real-time progress updates and completion notices without polling.

Clients register a handler implementing `AppServerNotificationHandler` to process events such as `turnProgress` updates. This bidirectional communication pattern allows the plugin UI to display streaming progress while the underlying HTTP transport remains stateless for method calls.

## Implementing the Client: Practical Code Examples

The **`CodexAppServerClient`** class in [`plugins/codex/scripts/lib/app-server-client.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-client.ts) wraps the HTTP transport, handling JSON-RPC envelope construction and type parsing. Below are practical implementations demonstrating key protocol interactions.

Initialize the client connection:

```typescript
import { CodexAppServerClient, CodexAppServerClientOptions } from './lib/app-server-client';

const opts: CodexAppServerClientOptions = {
  env: process.env,
  clientInfo: { name: 'my-plugin', version: '1.0.0' },
  capabilities: { canInterrupt: true },
};
const client = new CodexAppServerClient(opts);

```

Initialize the server session:

```typescript
async function initServer() {
  const initParams = { /* InitializeParams fields */ };
  const initResp = await client.request('initialize', initParams);
  console.log('Server ready, capabilities:', initResp.capabilities);
}

```

Start a new Codex thread:

```typescript
async function startThread() {
  const startParams = {
    name: 'feature-xyz',
    repoPath: process.cwd(),
    // persistExtendedHistory omitted per trimmed type definition
  };
  const startResp = await client.request('thread/start', startParams);
  console.log('Thread created:', startResp.threadId);
}

```

Initiate a code review:

```typescript
async function startReview(threadId: string) {
  const reviewParams = {
    threadId,
    target: { type: 'branch', ref: 'main' },
  };
  const reviewResp = await client.request('review/start', reviewParams);
  console.log('Review queued, job ID:', reviewResp.jobId);
}

```

Listen for server notifications:

```typescript
client.onNotification((msg) => {
  if (msg.type === 'turnProgress') {
    console.log(`Turn ${msg.turnId} progress: ${msg.percentage}%`);
  }
});

```

## Key Source Files and Type Definitions

Four primary files define the app server protocol for Codex plugin communication:

- **[`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts)** – Central TypeScript definitions containing `AppServerMethodMap`, request/response interfaces, and notification types.
- **[`plugins/codex/scripts/lib/app-server-client.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-client.ts)** – HTTP client implementation that serializes typed method calls into POST requests and dispatches incoming notifications.
- **[`plugins/codex/scripts/codex.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/codex.ts)** – Main plugin entry point that orchestrates user commands (`/codex:review`, `/codex:rescue`) by invoking the appropriate RPC methods.
- **`.generated/app-server-types/`** – Build-time generated TypeScript definitions providing low-level shape definitions for all protocol payloads, imported by the main protocol definition file.

## Summary

- The Codex plugin uses a **JSON-RPC-style protocol** over HTTP POST requests to `localhost:8080` for all synchronous operations.
- Type safety is enforced through **`AppServerMethodMap`** in [`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts), covering methods like `initialize`, `thread/start`, and `review/start`.
- **Asynchronous notifications** flow from server to client via the `AppServerNotification` system, enabling real-time progress tracking without polling.
- The **`CodexAppServerClient`** class abstracts transport details, automatically handling JSON-RPC envelopes and TypeScript type parsing.
- Third-party scripts can leverage the same protocol used by the Claude Code UI to drive Codex programmatically.

## Frequently Asked Questions

### What transport mechanism does the Codex plugin use to communicate with the App Server?

The Codex plugin communicates via standard HTTP POST requests to a local endpoint (default `localhost:8080`), sending JSON-RPC 2.0 formatted payloads. Each request contains a method name and parameters, while responses include either the typed result or a structured error object.

### How are server notifications handled in the Codex App Server protocol?

Server notifications use an asynchronous push model where the server sends `AppServerNotification` messages to registered clients. Developers implement the `AppServerNotificationHandler` callback—typically via `client.onNotification()`—to process events like `turnProgress` updates without blocking the main request-response cycle.

### Where are the type definitions for the App Server protocol located?

The primary type definitions reside in **[`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts)**, which imports low-level shapes from **`.generated/app-server-types/`**. These files define the `AppServerMethodMap`, individual request/response interfaces (such as `ThreadStartParams` and `ReviewStartResponse`), and notification types.

### Can third-party scripts use the Codex App Server protocol?

Yes, any script can utilize the protocol by importing the **`CodexAppServerClient`** class from [`plugins/codex/scripts/lib/app-server-client.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-client.ts) and following the method signatures defined in [`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts). This enables programmatic control of Codex operations identical to the native Claude Code UI integration.