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

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.

// 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.

// 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}