# codex-mcp-bridge

MCP server that lets an MCP client (Claude Code) drive OpenAI Codex as a
sub-agent: many independent or threaded queries, plus actions (shell
commands, file edits) when explicitly opted into.

Important: this project does not call the OpenAI HTTP API. It drives the
Codex CLI (the `codex` executable) locally and/or reads local Codex session
files. Authentication and session state come from the locally-installed
`codex` CLI (for example, `codex login`), and the bridge operates against
that local CLI and its session files rather than an external API key or
billing endpoint.

## Auth

Uses whatever `codex login` has already set up on this machine — a ChatGPT
subscription login, not API-key billing. The bridge launches the `codex`
executable as a child process so it inherits the current environment and the
CLI's local auth state. Do not try to configure `apiKey`/`baseUrl`/`env`
settings here: they are not used and `env` would replace the child's
environment rather than merging it, which breaks `codex` PATH resolution and
auth lookup.

Check status any time with:

```
codex login status
```

## Tool: `codex_ask`

One tool, parameterized:

- `prompt` (required), `working_directory` (required, absolute path — no
  implicit default, so Codex never silently operates on the wrong repo).
- `thread_id` — pass back the id returned by a previous call to continue
  that conversation; omit to start a new one. Threads are persisted by the
  Codex CLI itself (`~/.codex/sessions`), so ids remain valid across
  restarts of this server.
- `sandbox_mode` (`read-only` default / `workspace-write` / `danger-full-access`)
  and `approval_policy` (`never` default / `on-request` / `on-failure` /
  `untrusted`) — the "actions" knob. Default is read-only with no
  auto-approval: Codex can inspect the repo and answer, but cannot write
  files or run arbitrary commands unless a call explicitly asks for
  `workspace-write`. Since this runs non-interactively (`codex exec` under
  the hood), there's no one to answer an approval prompt either way —
  anything outside `sandbox_mode` is simply denied.
- `require_git_repo`, `additional_directories`, `network_access`,
  `web_search`, `model`, `reasoning_effort`, `output_schema` (JSON Schema
  for structured output), `timeout_ms`.

Independent calls (different or omitted `thread_id`) run concurrently as
separate Codex conversations — that's what covers "many queries" alongside
a single ongoing thread.

## Tool: `codex_cloud_tasks`

Lists Codex Cloud background tasks, or (with `task_id`) shows one task's
status. Wraps `codex cloud list --json` / `codex cloud status <id>` directly
(not part of the CLI's documented surface) — these are undocumented/
experimental, so the JSON field names in the list output aren't guaranteed
stable across CLI versions. `status` has no `--json` form; its output is
passed through as-is.

## Tool: `codex_local_sessions`

Lists recent local Codex CLI sessions — the ones `codex resume` picks
from — most recently touched first. `codex resume` itself is an
interactive-only picker with no scriptable output, so this reads
`~/.codex/session_index.jsonl` directly instead (also undocumented). That
index only carries session id, current thread name, and last-updated time —
no live/idle status or working directory; a session can be renamed multiple
times, so entries are deduped by id, keeping the most recent name.

Note this index only records *interactively* created sessions. Threads
started programmatically (including by `codex_ask`) are real and resumable
but do not appear here.

## Tool: `codex_read_thread`

Reads the message history of **any** thread, interactive or programmatic, by
locating its rollout JSONL under `~/.codex/sessions` and parsing it. No API
call, no quota — it works even when the account is rate-limited.

- `thread_id` (required), `limit` (default 50, counts back from newest),
  `include_reasoning` (default false), `max_chars` (per-message truncation).

Returns the thread's `cwd` and `source` from its `session_meta` header along
with the messages.

## Notes on driving a thread you want to watch

A thread created programmatically never enters the interactive session index,
so it won't show up in `codex resume`'s default picker or the desktop app. If
you want to *watch* the conversation in the normal Codex UI, start the thread
there first, then pass its id to `codex_ask`.

Two behaviours worth knowing:

- The desktop UI does not live-tail a thread, and navigating to it in an
  existing window serves a cached copy. Open the thread in a **new window**
  to see externally injected messages.
- A turn that fails (e.g. rate limit) has *already* appended your message to
  the rollout. Rollouts are append-only, so a failed call is not a no-op.

## Build

```
npm install
npm run build
```

## Register with Claude Code (user scope)

```
claude mcp add codex-bridge --scope user -- node /absolute/path/to/codex-mcp-bridge/dist/index.js
```

## Probe scripts

`probe-*.mjs` are small standalone experiments used to work out the
behaviours above (app-server wire framing, what `codex mcp-server` exposes,
why `codex-reply` can't reach persisted threads, SDK-only resume). They are
not part of the server; each prints its usage when run without arguments.