# App Server Protocol Used by Codex-Plugin-CC's Broker: JSON-RPC over IPC

> Discover the app server protocol for openai codex-plugin-cc. Learn how its broker uses JSON-RPC over IPC with Unix domain sockets and named pipes for seamless communication.

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

---

**The broker communicates with the Codex app-server using a JSON-RPC 1.0/2.0-style protocol delivered over local IPC channels, utilizing Unix domain sockets on macOS and Linux and named pipes on Windows.**

The openai/codex-plugin-cc repository implements a broker architecture that mediates communication between client processes and the Codex app-server. Understanding the app server protocol used by codex-plugin-cc's broker is essential for developers building plugins or debugging connectivity issues. The protocol relies on newline-delimited JSON-RPC messages exchanged over platform-specific IPC transports.

## Protocol Overview

The broker implements a **JSON-RPC 1.0/2.0-style protocol** that transmits structured messages between the client and the app-server. Each message contains standard JSON-RPC fields including `id`, `method`, `params`, and `result` or `error` as defined in the generated type definitions ([`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)).

## IPC Transport Layer

The transport mechanism is platform-specific:

- **Unix-like systems**: Uses **Unix domain sockets** with paths formatted as `unix:/path/to/broker.sock`
- **Windows**: Uses **named pipes** with paths formatted as `pipe:\\.\pipe\...-codex-app-server`

The helper function `parseBrokerEndpoint` in `broker-endpoint.mjs` handles the abstraction of these transport paths.

### Creating Broker Endpoints

When initializing a broker session, the system generates an appropriate endpoint string based on the operating system.

```javascript
import { createBrokerEndpoint } from "plugins/codex/scripts/lib/broker-endpoint.mjs";

const endpoint = createBrokerEndpoint("/tmp/cxc-12345", "darwin");
// → "unix:/tmp/cxc-12345/broker.sock"

```

This function resides in `plugins/codex/scripts/lib/broker-endpoint.mjs` (lines 10-16).

### Parsing Endpoint Strings

The broker and client use `parseBrokerEndpoint` to interpret endpoint strings and determine the transport mechanism.

```javascript
import { parseBrokerEndpoint } from "plugins/codex/scripts/lib/broker-endpoint.mjs";

const info = parseBrokerEndpoint("pipe:\\\\.\\pipe\\my-pipe");
// → { kind: "pipe", path: "\\\\.\\pipe\\my-pipe" }

```

This parsing logic is implemented in `plugins/codex/scripts/lib/broker-endpoint.mjs` (lines 24-31).

## Message Format and Communication

Messages follow a **newline-delimited JSON (NDJSON)** format, where each line represents a single JSON-RPC message. The JSON objects include the standard fields required for request/response correlation and method dispatch.

### Establishing Connections

The `CodexAppServerClient.connect` method automatically detects the presence of a broker endpoint and instantiates the appropriate client implementation.

```javascript
import { CodexAppServerClient } from "plugins/codex/scripts/lib/app-server.mjs";

const client = await CodexAppServerClient.connect(
  process.cwd(),
  { reuseExistingBroker: true }
);

// Send a JSON-RPC request
const init = await client.request("initialize", {
  clientInfo: { title: "MyTool", name: "my-tool", version: "1.0.0" },
  capabilities: {}
});

```

This connection logic is found in `plugins/codex/scripts/lib/app-server.mjs` (lines 35-49). When a broker endpoint is available, the method creates a `BrokerCodexAppServerClient` that opens the IPC channel and exchanges JSON-RPC messages.

### Handling Incoming Messages

The broker processes incoming data by splitting on newlines and parsing each JSON-RPC message individually.

```javascript
// Inside BrokerCodexAppServerClient.handleChunk()
socket.on("data", chunk => {
  // Each line = one JSON-RPC message
  const line = chunk.trim();
  const msg = JSON.parse(line);
  // Access msg.id, msg.method, msg.params...
});

```

This message handling implementation appears in `plugins/codex/scripts/lib/app-server.mjs` (lines 85-99).

## Key Source Files

The protocol implementation spans several files in the repository:

- **`plugins/codex/scripts/lib/broker-endpoint.mjs`**: Constructs and parses broker endpoint strings for both Unix sockets and Windows pipes.
- **`plugins/codex/scripts/lib/app-server.mjs`**: Implements the `CodexAppServerClient` class and `BrokerCodexAppServerClient` subclass, handling JSON-RPC serialization and IPC communication.
- **`plugins/codex/scripts/lib/broker-lifecycle.mjs`**: Manages broker session lifecycle, including spawning the broker process and awaiting IPC endpoint availability.
- **[`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)**: TypeScript definitions for JSON-RPC methods, parameters, and response types.
- **`tests/broker-endpoint.test.mjs`**: Unit tests verifying correct endpoint creation across platforms.

## Summary

- The codex-plugin-cc broker uses **JSON-RPC 1.0/2.0-style messages** exchanged over local IPC transports.
- **Unix domain sockets** handle communication on macOS and Linux, while **named pipes** are used on Windows.
- The `parseBrokerEndpoint` utility abstracts platform differences in path formatting.
- Messages are **newline-delimited JSON** containing standard JSON-RPC fields (`id`, `method`, `params`, `result`/`error`).
- The `BrokerCodexAppServerClient` class in `app-server.mjs` manages the connection and message exchange.

## Frequently Asked Questions

### What transport mechanism does codex-plugin-cc use on Windows?

On Windows, the broker communicates via **named pipes** using the format `pipe:\\.\pipe\...-codex-app-server`. The `parseBrokerEndpoint` function in `broker-endpoint.mjs` identifies these paths by their `pipe:` prefix and routes them accordingly.

### How does the broker handle multiple concurrent JSON-RPC requests?

The broker uses the standard JSON-RPC `id` field to correlate requests with responses. Each message is sent as a newline-delimited JSON object, allowing the client to match incoming results or errors with the originating request based on the unique identifier.

### Can I connect to the app-server without using the broker?

Yes. The `CodexAppServerClient` supports both direct spawning (`SpawnedCodexAppServerClient`) and broker-mediated connections (`BrokerCodexAppServerClient`). If no broker endpoint is provided, the client spawns the app-server directly and communicates via stdio rather than IPC.

### Where are the JSON-RPC method types defined?

Type definitions for the app-server protocol are located 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). This file contains the TypeScript interfaces for method names, parameter structures, and return types used in the JSON-RPC communication.