# Codex Desktop Bridge

A configurable MCP bridge for bidirectional handoff between any MCP client and Codex Desktop App Server, with durable callbacks and acknowledgements.

The primary journey starts in Codex:

```text
Codex task
  -> create_handoff (stable handoff_id, exact origin thread)
  -> your provider delivers the contract to an external MCP agent
  -> accept_handoff -> report_handoff(working|completed|failed)
  -> bridge calls Codex App Server turn/start on the original task
  -> get_handoff_status -> ack_handoff
```

The handoff and callback inbox survive bridge restarts. Agent and origin capabilities are scoped to one handoff, and an accepted handoff is bound to one external agent session. The bridge does **not** claim it can wake a closed ChatGPT, Claude, Grok, Cursor, or other client; the actual provider must deliver the outbound contract.

Provider adapters such as Slack may carry notifications or handoff contracts, but they are optional delivery surfaces, not the local control plane. The canonical task identity, return path, durable inbox, and acknowledgement remain in the App Server + bridge protocol. See the [Slack comparison and boundary](docs/related-projects.md#slack-as-an-optional-transport-not-the-control-plane).

## Why this project

Codex App Server already provides the authoritative thread and turn APIs. This project keeps those low-level operations available, then adds the missing application-level handshake: durable handoff state, session isolation, idempotent event delivery, callbacks, and acknowledgement.

It is not a terminal scraper, a transcript parser, a private Desktop IPC client, or a general workflow scheduler. It launches the documented `codex app-server --stdio` interface and uses `thread/list`, `thread/read`, `thread/start`, `thread/resume`, `thread/fork`, and `turn/start`.

## Requirements

- macOS
- Node.js 22.13 or newer
- An installed, authenticated OpenAI Codex binary whose `codex app-server --stdio` interface is usable

App Server is a versioned product interface that continues to evolve. The bridge probes the installed Codex version at runtime and returns clear protocol failures instead of promising compatibility with every future release.

## Install

```bash
npm install -g codex-desktop-bridge
codex-desktop-bridge --version
```

From a source checkout:

```bash
npm install
npm test
npm install -g .
```

## Standard MCP client configuration

For stdio clients such as ChatGPT-compatible local runtimes, Claude, Grok integrations, Cursor, and other MCP hosts:

```json
{
  "mcpServers": {
    "codex-desktop-bridge": {
      "command": "codex-desktop-bridge",
      "args": ["stdio", "--config", "/absolute/path/to/config.json"]
    }
  }
}
```

For direct Streamable HTTP:

```bash
codex-desktop-bridge http --config /absolute/path/to/config.json
```

The default HTTP listener is loopback-only at `http://127.0.0.1:8392/mcp`. A non-loopback listener is rejected unless bearer authentication is configured. See [examples/config.example.json](examples/config.example.json) and [docs/client-configuration.md](docs/client-configuration.md).

## Handoff tools

- `create_handoff`: bind an outbound contract to one existing Codex task and return one-time agent/origin capabilities.
- `accept_handoff`: bind the agent capability to one external session.
- `read_handoff`: read the exact accepted contract and its event history.
- `report_handoff`: durably record `working`, `completed`, or `failed`, then inject the update into the original Codex task.
- `get_handoff_status`: let the origin retrieve durable state.
- `ack_handoff`: acknowledge a terminal handoff.

The state machine is `dispatched -> accepted -> working -> completed|failed -> acknowledged`. A unique `event_id` makes retries idempotent.

## Low-level tools

The bridge also exposes `list_codex_tasks`, `read_codex_task`, `create_codex_task`, `resume_codex_task`, `send_to_codex_task`, `fork_codex_task`, `report_callback`, `report_to_chatgpt`, `list_callbacks`, `read_callback`, and `ack_callback`.

Read does not resume a task. Resume/send/fork are explicit mutations and require an exact repo/worktree contract. A callback belongs to one explicit client session.

## Transports and configuration

The same package supports standard MCP stdio and direct Streamable HTTP. Configuration covers the Codex binary, optional `CODEX_HOME`, state database, request/task timeouts, HTTP host/port/path/auth/public URL, allowed origins, and log level. Secret bearer values come from a referenced file or environment variable and are never included in `bridge_info`.

See [docs/protocol.md](docs/protocol.md) for isolation and restart semantics.

## Related projects and design choice

Before the first release, the project compared existing App Server bridges and chose an independent implementation. The low-level protocol comes directly from OpenAI's App Server documentation; no third-party source code was copied. [docs/related-projects.md](docs/related-projects.md) records the bounded comparison and licenses. This project does not claim to be the first Codex bridge.

## License

Apache-2.0. See [LICENSE](LICENSE).