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.

Related MCP server: Codex Claude Code MCP

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:

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:

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

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:

claude mcp remove --scope user codex-collab

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

Development and verification

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, which OpenAI labels experimental, and the official MCP TypeScript SDK. It does not use the removed codex mcp-server command. Connection setup follows Claude Code's MCP documentation.