What Is the Codex Plugin Broker Endpoint and How It Communicates with the App Server

The broker endpoint is a platform-specific transport string—either a Windows named pipe or Unix domain socket—that enables lightweight IPC between the Codex app-server and client components, allowing multiple processes to share a single server instance via JSON-RPC messages sent over a socket connection.

The openai/codex-plugin-cc repository implements a broker endpoint mechanism to facilitate inter-process communication between the long-running app-server and various client components. This architecture eliminates the overhead of repeatedly spawning new server processes by providing a persistent connection point that clients can reference and reuse across multiple operations.

What Is the Broker Endpoint?

The broker endpoint is a string that encodes the transport mechanism and address for reaching a running app-server process. Rather than spawning a new server for every command, the Codex Plugin uses this endpoint to establish a reusable communication channel.

Endpoint Generation and Platform Abstraction

The endpoint is generated by createBrokerEndpoint(sessionDir, platform) in plugins/codex/scripts/lib/broker-endpoint.mjs. The function abstracts operating system differences by selecting either Windows named pipes or Unix domain sockets based on the platform:

// On Windows → pipe:\\.\pipe\<sanitized-session-name>-codex-app-server
// On POSIX → unix:<sessionDir>/broker.sock
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")}`;
}

On Windows, the function returns a string prefixed with pipe: followed by the named pipe path. On POSIX systems, it returns a unix: prefix followed by the absolute path to a socket file within the session directory.

Environment Variable Configuration

Once generated, the endpoint string is exposed to clients through the CODEX_COMPANION_APP_SERVER_ENDPOINT environment variable. This constant is defined as BROKER_ENDPOINT_ENV in plugins/codex/scripts/lib/app-server.mjs and exported when the app-server starts in broker mode. Clients can discover the active endpoint by reading this environment variable or by loading a broker session file from the filesystem.

How the Broker Endpoint Communicates with the App Server

Communication proceeds through a three-phase process: parsing the endpoint string, establishing the socket connection, and exchanging JSON-RPC messages.

Parsing the Transport String

When a client obtains the endpoint string, it calls parseBrokerEndpoint(endpoint) from broker-endpoint.mjs to extract the transport type and concrete path:

export function parseBrokerEndpoint(endpoint) {
  if (endpoint.startsWith("pipe:")) {
    return { kind: "pipe", path: endpoint.slice("pipe:".length) };
  }
  if (endpoint.startsWith("unix:")) {
    return { kind: "unix", path: endpoint.slice("unix:".length) };
  }
  throw new Error(`Unsupported broker endpoint: ${endpoint}`);
}

This function returns an object with kind (either "pipe" or "unix") and the path necessary for Node.js's net module to establish a connection.

Establishing the Socket Connection

Using the parsed result, the client creates a net.Socket connection via net.connect(). In plugins/codex/scripts/lib/app-server.mjs, the BrokeredCodexAppServerClient class handles this connection:

import net from "node:net";
import { parseBrokerEndpoint } from "./broker-endpoint.mjs";

const endpoint = process.env.CODEX_COMPANION_APP_SERVER_ENDPOINT;
const { kind, path } = parseBrokerEndpoint(endpoint);

const socket = net.connect({ path }, () => {
  console.log(`Connected to app-server via ${kind}`);
});

The socket provides a bidirectional byte stream that serves as the foundation for all subsequent communication.

JSON-RPC Message Exchange

Once connected, the client and app-server communicate using the protocol defined in [app-server-protocol.d.ts](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts). The client sends JSON-RPC requests and notifications over the socket using the sendMessage method implemented in BrokeredCodexAppServerClient:

// Send a JSON-RPC request example
socket.write(JSON.stringify({ 
  jsonrpc: "2.0", 
  id: 1, 
  method: "initialize", 
  params: {} 
}) + "\n");

The app-server processes these messages and returns responses through the same socket, enabling multiple clients to multiplex operations through a single server instance.

Broker Mode vs. Direct Process Spawning

The Codex Plugin supports two client implementations defined in app-server.mjs:

• SpawnedCodexAppServerClient – Spawns a new codex app-server process directly and communicates via stdio. Used when no broker endpoint is available.
• BrokeredCodexAppServerClient – Connects to an existing server via the broker endpoint socket. Used when CODEX_COMPANION_APP_SERVER_ENDPOINT is set or when loadBrokerSession(cwd) returns a valid endpoint (as implemented in plugins/codex/scripts/lib/codex.mjs at line 907).

import { loadBrokerSession } from "./broker-lifecycle.mjs";

async function getClient(cwd) {
  const envEndpoint = process.env.CODEX_COMPANION_APP_SERVER_ENDPOINT;
  const session = await loadBrokerSession(cwd);
  const endpoint = envEndpoint ?? session?.endpoint ?? null;

  if (endpoint) {
    // Broker mode – connect to existing socket
    const client = new BrokeredCodexAppServerClient(cwd, { brokerEndpoint: endpoint });
    await client.initialize();
    return client;
  } else {
    // Direct mode – spawn a new app-server process
    const client = new SpawnedCodexAppServerClient(cwd);
    await client.initialize();
    return client;
  }
}

Summary

• The broker endpoint is a transport string (pipe: on Windows, unix: on POSIX) generated by createBrokerEndpoint() that specifies how to reach a running app-server.
• Environment discovery happens via CODEX_COMPANION_APP_SERVER_ENDPOINT or session files loaded by loadBrokerSession().
• Connection flow involves parsing the endpoint with parseBrokerEndpoint(), then establishing a net.Socket to the specified path.
• Protocol uses JSON-RPC over the socket, enabling multiple clients to share one app-server instance.
• Fallback behavior automatically spawns a new server via SpawnedCodexAppServerClient if the broker endpoint is unavailable or the connection fails.

Frequently Asked Questions

What transport protocols does the broker endpoint support?

The broker endpoint supports Windows named pipes (format: pipe:\\.\pipe\<name>) and Unix domain sockets (format: unix:<path>). The parseBrokerEndpoint() function in broker-endpoint.mjs handles both formats and throws an error for unsupported schemes.

How does the client decide whether to use broker mode or spawn a new server?

The client checks for the CODEX_COMPANION_APP_SERVER_ENDPOINT environment variable first, then falls back to loadBrokerSession(cwd)?.endpoint as implemented in codex.mjs. If an endpoint exists, it instantiates BrokeredCodexAppServerClient; otherwise, it uses SpawnedCodexAppServerClient to launch a fresh process.

Where is the broker endpoint string stored between sessions?

The endpoint is stored in the CODEX_COMPANION_APP_SERVER_ENDPOINT environment variable (defined as BROKER_ENDPOINT_ENV in app-server.mjs) and optionally persisted to a session file on disk that loadBrokerSession() can retrieve later.

What happens if the broker socket connection is lost?

The BrokeredCodexAppServerClient detects disconnections through the socket's error and close events. According to the handleExit implementation in app-server.mjs, the client can then trigger a cleanup sequence, optionally restart the server, or fall back to spawning a new direct-connection client to maintain availability.

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