# Claude Codex Connector

Keep Claude Code as your main conversation and give it Codex as a background
collaborator. Claude can assign work, continue its own task, send corrections,
read Codex's progress and results, and request a stop through four MCP tools.

Codex builds this standalone connector. It is reusable in other projects and is
independent of the Corporate Brain project.

## Watch Claude and Codex work together

Start a fresh Claude Code session (or reconnect `codex-collab`) to load the viewer.
Ask:

> Have Codex review this project, and show me the live exchange viewer.

Claude receives a private local link with the tool result and is instructed to
share it. Open that link in your browser, or give it to Codex to open in its browser
panel. For an existing task, ask Claude to call `codex_status` and show its
`viewer_url`. No reinstall is needed for an existing registration to this folder.

The page has a task list and an ordered exchange showing:

- The exact assignment Claude sends to Codex and its follow-up messages.
- Whether each follow-up was accepted, rejected, or its delivery is uncertain.
- Codex's progress messages and final answer, plus running/completed/stopped/failed
  task status. A final answer can arrive before completion is confirmed.
- When Claude last checked task status. Refreshing the page does not count as a
  Claude check, and a check does not prove Claude understood or agreed.

The viewer refreshes about every two seconds without making model calls. It shows
completed progress messages, not each token as it is generated. It includes only
messages shared through this connector, not Claude's full conversation, private
reasoning, or full terminal output. Each connector connection has its own page;
there is no combined dashboard across all projects.

The page works while its owning Claude MCP connection is open. Closing/restarting
that connection ends the page and clears its in-memory history; a new connection
gets a new link. Up to 200 recent events per task and 32,000 characters per message
are retained, with missing older events marked. Keep the link private: it grants
read access to that session from your computer. The connector does not save viewer
message content, although the underlying apps, browser history, or screenshots may
retain their normal records. The link works on the computer running the connector.

If local viewing is unavailable, Claude receives `viewer_error` and collaboration
can continue. Add `--no-viewer` to the MCP server arguments to disable the listener.

## Setup

Requires Node 22+, Git, Claude Code and Codex installed and signed in. The tested
versions and live verification results are recorded in `docs/verification.md`.

From this folder:

```sh
npm install
npm run doctor
node scripts/install.mjs --scope user
```

The last command registers `codex-collab` for Claude Code across your projects.
It references this folder, so keep the folder in place. Start a fresh Claude Code
session in the project you want to work on. The connector uses that session's
working folder; it does not hard-code this project's path.

For only one project, run the installer by its absolute path from that project's
folder and omit `--scope user` (default: local). `--scope project` writes a shared
project configuration instead. `--print` prints the configuration without installing.
For an unusual Codex location, set `CODEX_BIN` when installing. The installer
needs a `codex` command; if `which codex` prints nothing, point `CODEX_BIN` at the
copy bundled with the ChatGPT desktop app on macOS:

```sh
CODEX_BIN=/Applications/ChatGPT.app/Contents/Resources/codex node scripts/install.mjs --scope user
```

Without it the connector exits at startup with `spawn codex ENOENT`, which Claude
Code reports as `CONNECTION_CLOSED`.

Model selection follows your Codex configuration unless you explicitly name a model in a task.

Try this in Claude Code:

> Use codex-collab to have Codex review the project in read-only mode and identify
> its three main risks. While it works, inspect the README yourself. Send Codex any
> questions you discover, then compare its answer with your findings.

For implementation, commit your current work first:

> Have Codex implement [bounded feature] with workspace-write, in its own working
> folder and branch. While it works, I'll work with you on [independent task].
> Review and test its changes before we combine them.

## Planning together

For every new project-planning, design, structure or architecture decision, including
revisions that reopen a decision, Claude is instructed to automatically start a fresh
read-only Codex task before finalizing the plan. You do not need to ask for Codex
separately. Claude gives it a neutral brief of the goal, constraints, relevant paths
and facts, user requirements, settled constraints and open choices, without making
Claude's preferred answer the premise. Claude forms its initial view separately
while Codex evaluates.

Codex returns a recommendation, viable alternatives, tradeoffs and risks, assumptions,
and evidence that could change its view. Claude collects the completed opinion,
compares both views, names disagreements, and explains accepted and rejected
suggestions before presenting a recommendation. Follow-up messages use `codex_send`
only after the initial independent opinion. Separate conversations do not guarantee
freedom from one model's framing influencing the other.

Related choices can share one bounded brief, but new decisions must not be skipped.
Mechanical implementation of an agreed plan does not require another consultation
unless it raises a new design choice. If Codex is unavailable, fails or hits limits,
Claude must disclose the missing second input without implying consensus and keep
that decision pending unless the user explicitly chooses to proceed alone. Unrelated
useful work can continue. There is no automatic API-key or billing-provider fallback.

The policy is delivered through MCP initialization instructions to every connected
project; it does not depend on copying this repository's `CLAUDE.md`. It is a standing
agent instruction, not code that intercepts every Claude response, so instruction
following cannot be guaranteed. Start a fresh Claude session or reconnect to load
updated instructions. No reinstall is required.

## Tools

| Tool | Inputs | Behavior |
| --- | --- | --- |
| `codex_start` | `prompt`, optional `mode`, `label`, `model` | Returns task ID and folder after admission, before Codex finishes. |
| `codex_send` | `task_id`, `message` | Adds a message to a running task or starts a follow-up in the same Codex conversation. |
| `codex_status` | optional `task_id`, `after`, `wait_ms` | Lists tasks or returns new progress/results. Use `next_cursor` as the next `after`; waits are capped at 20 seconds. |
| `codex_stop` | `task_id` | Requests interruption; check status for confirmation. |

Two tasks may be active per connection. Each task has a ten-minute turn limit.
Claude checks for messages; this first version does not automatically wake an idle
Claude conversation. Both agents retain their own histories. MCP supplies shared
messages and results, not a merged internal conversation.

`read-only` is the default: Codex inspects the same files Claude sees, so reads can
observe Claude's changing files. Use a committed snapshot when review consistency
matters. `workspace-write` creates a **git worktree**, a separate working folder and
branch of the project. It starts from a clean committed project and does not copy
ignored files, secrets, or installed dependencies. Set up dependencies there if the
task needs them. Branches and folders are kept for review; nothing merges or deletes
them automatically. The status result gives the folder and branch paths.

## How it runs and stops

Claude launches the connector as an MCP process. The connector launches its own
Codex App Server process and starts a separate Codex conversation for each task.
Messages and completed agent responses become status events. A read-only HTTP
viewer listens only on this computer at 127.0.0.1, using a random port and private
access token. No cloud service or API-key database is added.

Codex uses its existing local account and configuration. ChatGPT login uses
subscription allowance; API-key login instead uses separately billed API access.
`codex login status` verified ChatGPT login on 2026-09-11. Claude's coordination
consumes Claude usage. Changing
authentication or provider could change billing. The bridge does not automatically
switch to an API key or another billing provider. No extra paid API service is
introduced by the bridge. Normal sandbox restrictions remain in force and approval
requests are not automatically granted. This is local collaboration software, not
a security boundary for untrusted projects or agents.

Closing Claude's MCP connection shuts down its background Codex process. In-memory
tasks do not resume automatically after a crash or restart. Private diagnostic
summaries and worktrees are stored under `~/.claude-codex-connector/`; summaries
contain task IDs, folder paths, and status, but omit prompts, answers, command
output, and reasoning. Treat the retained working folders as private project data. The
underlying Codex tool may also save normal local conversation records. Task folders
remain available for manual review and cleanup.

Uninstall the connection with:

```sh
claude mcp remove --scope user codex-collab
```

This removes registration, not code, conversation records, branches, or task folders.

## Development and verification

```sh
npm test             # Offline tests; no model calls
npm run doctor       # Versions and login checks; no model calls
npm run smoke        # Real Claude + Codex test; uses account usage
npm run smoke:edit   # Real isolated Codex edit in a disposable Git project
node scripts/planning-smoke.mjs # Real automatic independent planning consultation
node scripts/viewer-demo.mjs --hold # Real Claude/Codex exchange; view it for 20 min
```

The live smoke test uses a disposable folder. Claude starts Codex, writes its own
file while Codex is active, sends a unique follow-up marker, then checks the result.
It records timestamps and verifies that Claude's work preceded Codex's final answer.
The editing smoke test verifies a real file change in Codex's separate working
folder while the original folder remains clean.

The connector uses [Codex App Server](https://learn.chatgpt.com/docs/app-server),
which OpenAI labels experimental, and the official
[MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
It does not use the removed `codex mcp-server` command. Connection setup follows
[Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp).