Broker Endpoint for Codex Communication: Platform-Specific Transport Mechanisms

The broker endpoint for Codex communication is a platform-specific transport generated by createBrokerEndpoint that resolves to Unix-domain sockets (unix:<session-dir>/broker.sock) on Linux and macOS, or Windows named pipes (pipe:\\.\pipe\<sanitized-name>-codex-app-server) on Windows systems.

The broker endpoint for Codex communication serves as the critical transport layer between the Codex plugin and the internal app-server in the openai/codex-plugin-cc repository. This endpoint is dynamically constructed based on the session directory and host operating system, ensuring secure local inter-process communication across different platforms.

How the Broker Endpoint Is Generated

The endpoint generation logic resides in plugins/codex/scripts/lib/broker-endpoint.mjs, which exports the createBrokerEndpoint helper. This function accepts a session directory path and returns a formatted broker endpoint string specific to the platform.

POSIX Systems (Linux and macOS)

On POSIX systems, the function constructs a Unix-domain socket path by appending broker.sock to the session directory. The resulting endpoint follows the format unix:<session-dir>/broker.sock. For example, a session directory of /tmp/session-abc produces unix:/tmp/session-abc/broker.sock.

Windows Named Pipes

On Windows, the implementation sanitizes the session directory name to remove illegal filesystem characters, then constructs a named pipe path. The format is pipe:\\.\pipe\<sanitized-session-name>-codex-app-server. This creates a unique named pipe for each Codex session while ensuring compatibility with Windows naming conventions.

Implementation in the Codex Plugin

The generated endpoint is consumed by plugins/codex/scripts/app-server-broker.mjs to initialize the broker process. This file uses the endpoint string to establish the communication channel between the plugin and the app-server. Additionally, parseBrokerEndpoint (also exported from broker-endpoint.mjs) handles reverse parsing of endpoint strings when connecting to existing broker processes. Unit tests validating these formats are located in tests/broker-endpoint.test.mjs.

Code Examples

Here are practical examples of generating broker endpoints for different platforms using the createBrokerEndpoint function.

POSIX systems (Linux/macOS):

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

const sessionDir = "/tmp/codex-session-123";
const endpoint = createBrokerEndpoint(sessionDir);
// Returns: "unix:/tmp/codex-session-123/broker.sock"
console.log(endpoint);

Windows systems:

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

const sessionDir = "C:\\Users\\Dev\\Sessions\\codex-session-123";
const endpoint = createBrokerEndpoint(sessionDir, "win32");
// Returns: "pipe:\\\\.\\pipe\\codex-session-123-codex-app-server"
console.log(endpoint);

Summary

• The broker endpoint for Codex communication is generated by createBrokerEndpoint in plugins/codex/scripts/lib/broker-endpoint.mjs.
• Linux/macOS: Uses Unix-domain sockets with the format unix:<session-dir>/broker.sock.
• Windows: Uses named pipes with the format pipe:\\.\pipe\<sanitized-name>-codex-app-server.
• The app-server-broker.mjs module consumes this endpoint to establish the broker process.
• Unit tests in tests/broker-endpoint.test.mjs validate the platform-specific formatting.

Frequently Asked Questions

What file generates the broker endpoint for Codex communication?

The broker endpoint is generated by the createBrokerEndpoint function exported from plugins/codex/scripts/lib/broker-endpoint.mjs in the openai/codex-plugin-cc repository. This utility handles both Unix socket and Windows named pipe creation based on the platform.

Why does Windows use a named pipe instead of a Unix socket?

Windows does not support Unix-domain sockets in the same way POSIX systems do. Instead, the Codex plugin uses Windows named pipes (pipe:\\.\pipe\...) which provide equivalent local inter-process communication capabilities. The implementation sanitizes the session name to ensure valid pipe naming conventions.

How is the session directory sanitized on Windows?

The createBrokerEndpoint function removes illegal filesystem characters from the session directory name before constructing the pipe path. This ensures the resulting named pipe conforms to Windows naming requirements while maintaining uniqueness for the Codex session.

Can I parse an existing broker endpoint string back into components?

Yes. The broker-endpoint.mjs module exports parseBrokerEndpoint, which reverses the formatting operation to extract the session directory and platform type from an existing endpoint string. This is used internally when connecting to existing broker processes.

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