# How Broker Endpoint Communication Functions Between Claude Code and Codex Across Platforms

> Discover how broker endpoint communication works between Claude Code and Codex on Windows and POSIX platforms. Learn about platform-specific transports and unified JSON messaging.

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

---

**Broker endpoint communication between Claude Code and Codex uses platform-specific transports—named pipes on Windows and Unix-domain sockets on POSIX systems—wrapped in a unified addressing schema that enables bidirectional JSON message exchange.**

The Claude Code plugin and Codex companion rely on a **broker endpoint** to abstract OS-specific transport mechanisms. This architecture, implemented in the `openai/codex-plugin-cc` repository, allows seamless session transfer and real-time messaging between the Claude editor and Codex runtime regardless of whether the host runs Windows, Linux, or macOS.

## Endpoint Creation and Platform Abstraction

When a Codex session initializes, the plugin constructs a broker address from the session directory using the `createBrokerEndpoint` function. This helper isolates platform detection logic to ensure consistent addressing across operating systems.

On **Windows** (`process.platform === "win32"`), the function generates a **named pipe** address following the `pipe:\\.\pipe\{name}` schema. On **POSIX** systems (Linux/macOS), it returns a **Unix-domain socket** path using the `unix:/path/to/broker.sock` format.

```js
// plugins/codex/scripts/lib/broker-endpoint.mjs
export function createBrokerEndpoint(sessionDir, platform = process.platform) {
  if (platform === "win32") {
    const pipeName = sanitizePipeName(
      `${path.win32.basename(sessionDir)}-codex-app-server`
    );
    return `pipe:\\\\.\\pipe\\${pipeName}`;
  }
  return `unix:${path.join(sessionDir, "broker.sock")}`;
}

```

The function accepts a `sessionDir` parameter representing the temporary session directory and an optional `platform` parameter that defaults to `process.platform`. This design enables deterministic testing while allowing runtime platform detection.

## Endpoint Parsing and Validation

Both Claude Code and Codex use a shared parser to convert endpoint strings into structured objects. The `parseBrokerEndpoint` function validates input and returns a discriminated union with `kind` and `path` properties.

```js
// plugins/codex/scripts/lib/broker-endpoint.mjs
export function parseBrokerEndpoint(endpoint) {
  if (typeof endpoint !== "string" || endpoint.length === 0) {
    throw new Error("Missing broker endpoint.");
  }
  if (endpoint.startsWith("pipe:")) {
    const pipePath = endpoint.slice("pipe:".length);
    if (!pipePath) throw new Error("Broker pipe endpoint is missing its path.");
    return { kind: "pipe", path: pipePath };
  }
  if (endpoint.startsWith("unix:")) {
    const socketPath = endpoint.slice("unix:".length);
    if (!socketPath) throw new Error("Broker Unix socket endpoint is missing its path.");
    return { kind: "unix", path: socketPath };
  }
  throw new Error(`Unsupported broker endpoint: ${endpoint}`);
}

```

This parser ensures both sides agree on the transport type before attempting connection. If the endpoint string lacks the required `pipe:` or `unix:` prefix, or if the path component is empty, the function throws descriptive errors that fail fast during initialization.

## Transport Layer Implementation

The actual network layer implementation differs by platform but exposes a unified interface through Node.js's `net` module.

On **Windows**, the server binds to the pipe name using `net.createServer` and listens on the `\\.\pipe\{name}` namespace. Clients connect using `net.connect(pipeName)`.

On **Unix**, the server listens on the socket file path created in the session directory. Clients connect using `net.connect(socketPath)`.

The core server logic resides in **`plugins/codex/scripts/app-server-broker.mjs`**, which opens the transport listener, negotiates a JSON-over-TCP protocol, and forwards messages to the Codex runtime. This file handles connection lifecycle management and message routing independently of the underlying transport mechanism.

## Session Handshake and Bidirectional Messaging

The broker endpoint facilitates a three-phase handshake that transfers session context from Claude Code to Codex.

First, Claude Code serializes a **session transfer** payload containing the session directory, environment variables, and configuration using the utilities in **`plugins/codex/scripts/lib/claude-session-transfer.mjs`**. This payload mirrors the endpoint creation logic to ensure address consistency.

Second, the serialized JSON payload transmits over the broker connection to the endpoint parsed by `parseBrokerEndpoint`. The Codex side receives this payload, materializes the session directory, and spawns the appropriate **app-server** process.

Third, both ends maintain the channel for the duration of the editing session, exchanging bidirectional messages including `review` requests, `result` payloads, and `status` updates. The connection persists until the session terminates or the transport encounters an error.

## Cross-Platform Consistency

Because the endpoint string follows a well-defined schema using explicit `pipe:` or `unix:` prefixes, the same high-level communication logic executes on every platform. Platform-specific nuances—such as Windows pipe naming conventions or Unix socket file permissions—remain isolated inside the `createBrokerEndpoint` helper.

This abstraction allows the rest of the plugin to remain transport-agnostic. Whether running on Windows 11 with named pipes or macOS with Unix sockets, the broker endpoint communication layer provides identical guarantees for message delivery and session state synchronization.

## Summary

- **Platform abstraction**: The `createBrokerEndpoint` function in `plugins/codex/scripts/lib/broker-endpoint.mjs` generates named pipes for Windows (`win32`) and Unix-domain sockets for Linux/macOS.
- **Validation layer**: `parseBrokerEndpoint` converts string addresses into structured `{kind, path}` objects while enforcing schema compliance.
- **Server implementation**: `plugins/codex/scripts/app-server-broker.mjs` manages the transport listener and JSON message routing using Node.js's `net` module.
- **Session transfer**: `plugins/codex/scripts/lib/claude-session-transfer.mjs` handles serialization of session context between Claude Code and Codex.
- **Bidirectional protocol**: The broker maintains persistent connections for command execution, result streaming, and status updates throughout the editing session.

## Frequently Asked Questions

### What transport mechanism does the broker endpoint use on Windows?

On Windows platforms, the broker endpoint uses **named pipes** with addresses formatted as `pipe:\\.\pipe\{sanitized-name}`. The `createBrokerEndpoint` function detects `process.platform === "win32"` and generates a pipe name derived from the session directory basename, appending `-codex-app-server` to ensure uniqueness.

### How does Codex validate incoming broker endpoint addresses?

Codex validates endpoints using the `parseBrokerEndpoint` function exported from `plugins/codex/scripts/lib/broker-endpoint.mjs`. This function checks that the input is a non-empty string, verifies it starts with either `pipe:` or `unix:`, and ensures the path component exists. Invalid formats trigger descriptive `Error` throws before any network connection attempts.

### What file handles the session transfer payload between Claude Code and Codex?

The **`plugins/codex/scripts/lib/claude-session-transfer.mjs`** module manages session transfer serialization. It prepares JSON payloads containing the session directory and environment context that Claude Code sends to Codex via the broker endpoint, enabling Codex to reconstruct the editing session state on its side.

### Why does the broker use different transport methods across platforms?

The broker uses **named pipes on Windows** and **Unix-domain sockets on POSIX** because these are the optimal IPC mechanisms provided by each operating system's kernel. Named pipes offer reliable byte-stream communication on Windows, while Unix sockets provide equivalent functionality with filesystem-based addressing on Linux and macOS. The unified addressing schema (`pipe:` vs `unix:`) allows the application code to remain identical across platforms while leveraging native performance characteristics.