Content
# Codex Bridge
Codex Bridge is a local control bridge for agent workbenches. It uses documented
Codex interfaces to start, steer, observe, and coordinate work without treating
structured runtime control as screen automation.
## Why it exists
Agent orchestrators need a stable way to drive coding workbenches, inspect
events, and retain artifacts. UI automation can help with visual tasks, but it
is a fragile foundation for session control. Codex Bridge exposes the structured
interfaces already provided by Codex.
## Core idea
```text
agent orchestrator
|
v
Codex Bridge
|
+-- codex app-server (rich session control)
+-- codex exec (one-shot jobs)
+-- codex:// links (open app surfaces)
+-- codex mcp-server (tool consumption)
```
Structured control comes first. Browser, desktop, or OS automation is reserved
for work that genuinely requires seeing or manipulating a visual surface.
## What Codex Bridge manages
- Codex CLI capability detection
- app-server JSON-RPC initialization
- thread and turn lifecycle helpers
- account preflight and supported login flows
- event-stream capture to operator-selected local files
- a Windows-to-WSL connector with scoped firewall and token authentication
- generated app-server protocol schemas
## Design principles
- Prefer documented runtime interfaces over UI scraping.
- Default to stdio or loopback-only transports.
- Require authentication for non-loopback listeners.
- Keep credentials and machine-specific evidence outside the repository.
- Treat generated schemas and observed behavior as versioned evidence.
- Make local paths configurable through `PATH`, `CODEX_BIN`, or script options.
## Repository layout
```text
docs/ Architecture, roadmap, and generalized connector guidance
evals/ Small machine-readable evaluation definitions
prompts/ Operator intent and safety contracts paired with scripts
scripts/ Deterministic host setup helpers
skills/ Project-local agent guidance
src/ CLI, bridge implementation, and generated protocol schemas
notes/ Public-safe note conventions; local run logs are ignored
```
## Current status
The repository contains an executable Codex capability probe, app-server smoke
paths, account checks, thread/turn helpers, a Windows host connector, a
generated app-server schema snapshot, and a first MCP facade (`src/mcp-server.mjs`)
exposing probe, account, and thread/turn control as MCP tools for local agent
orchestrators. The broader registry remains planned work.
Run the syntax checks:
```bash
npm run check
```
Run the capability probe when `codex` is on `PATH`:
```bash
npm run probe
```
Or select a local executable explicitly:
```bash
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex probe
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex app-server-smoke
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex account-status
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex account-login-start
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex account-login-cancel <login-id>
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex thread-smoke
CODEX_BIN=/path/to/codex node ./src/cli.mjs codex turn-smoke --events /tmp/codex-events.jsonl
```
`account-login-start` uses Codex app-server's supported device-code flow.
Codex Bridge does not copy credential files between Codex homes.
## MCP facade
`src/mcp-server.mjs` exposes Codex Bridge as a stdio MCP server for local agent
orchestrators (e.g. Claude Code):
```bash
npm run mcp
# or, once installed as a bin: codex-bridge-mcp
```
Tools: `codex_bridge_probe`, `codex_bridge_app_server_smoke`,
`codex_bridge_account_status`, `codex_bridge_account_login_start`,
`codex_bridge_account_login_cancel`, `codex_bridge_start_thread`,
`codex_bridge_list_threads`, `codex_bridge_resume_thread`, and
`codex_bridge_send_turn`. Turns always run with a read-only sandbox and
`approvalPolicy: never` — the server cannot execute shell commands or write
files, and callers cannot widen that policy through tool parameters.
By default, the MCP facade starts a local stdio app-server, preserving the
existing Claude Code workflow. To attach to a separately managed app-server,
such as the authenticated Windows connector, configure the MCP process with:
```bash
CODEX_APP_SERVER_URL=ws://host:48740
CODEX_APP_SERVER_TOKEN_FILE=/local/path/to/codex-bridge-ws-token.txt
```
The token may instead be supplied through `CODEX_APP_SERVER_TOKEN`, but a local
token file is preferred. Non-loopback WebSocket connections require one of
those two credential sources. Never put the token in repository config.
## Windows host connector
See [`docs/WINDOWS_CODEX_CONNECTOR.md`](docs/WINDOWS_CODEX_CONNECTOR.md). The
PowerShell helper starts an authenticated app-server listener and scopes its
firewall rule to explicitly supplied or automatically detected WSL addresses.
## Public/private model
This repository contains generalized code, documentation, generated schemas,
and synthetic examples. A private downstream repository or local control plane
should hold deployment values, real hostnames and addresses, operational run
logs, diagnostic transcripts, credential references, and environment-specific
configuration.
Never commit tokens, account state, private event logs, or machine-specific
proof artifacts here.
