Claude Science Codex Review

A privacy-conscious, asynchronous bridge that lets Claude Science delegate an independent review or implementation task to the official OpenAI Codex CLI.

Long Codex runs execute in a macOS user LaunchAgent, outside the Claude Science sandbox. Claude Science submits a job, receives a job ID immediately, and polls short MCP calls until the job reaches a terminal state. This avoids one-minute tool limits and prevents sandbox proxy variables from breaking Codex WebSocket TLS.

Community project. It is not an official OpenAI or Anthropic integration.

What It Installs

• a Claude Science skill with reliable submit, poll, failure, and follow-up behavior;
• an MCP server exposing codex, codex-status, codex-reply, codex-list-jobs, and codex-cancel;
• a durable local queue and host-side Codex runner;
• a macOS LaunchAgent and a read-only diagnostic command.

flowchart LR
  CS["Claude Science"] --> MCP["Queue-only MCP server"]
  MCP --> Q["Private local job queue"]
  Q --> R["Host LaunchAgent"]
  R --> CLI["Official Codex CLI"]
  CLI --> Q
  CS -->|"poll until terminal"| MCP

Requirements

• macOS 13 or newer (the tested installer platform)
• Claude Science with a local org skill directory
• Node.js 20 or newer; the installer prefers Claude Science's bundled Node
• the official Codex CLI, already authenticated with codex login

No OpenAI API key is accepted, copied, or stored.

Install

git clone https://github.com/gongchen0916/claude-science-codex-review.git
cd claude-science-codex-review
./install.sh

Restart Claude Science after installation. If macOS or Claude Science asks once for access to the local Codex state directory, grant that directory access, then verify:

claude-science-codex-doctor

See the Chinese quick start for a compact walkthrough.

Use

Ask Claude Science to have Codex independently review a paper figure, statistical analysis, source tree, reproducibility package, or proposed code change. Reviews default to the Codex read-only sandbox.

The critical lifecycle is:

1. codex returns a jobId immediately.
2. codex-status is called repeatedly while the job is queued, dispatching, or running.
3. Only completed, failed, or canceled is a final state.
4. A completed result may be followed up with codex-reply on the returned thread.

A queued job is not a review. The included skill explicitly prevents Claude Science from inventing findings or stopping before Codex returns a final agent message.

Model Names

Omitting model uses the Codex CLI default. The bridge maps the unsupported request alias gpt-5.6-codex to gpt-5.6-sol for compatible ChatGPT subscription sessions and records both requestedModel and actual model. Callers must disclose the model that actually ran.

Security

• Codex authentication remains owned by the official CLI.
• The bridge never reads Codex auth files or Claude Science credentials.
• Proxy variables are removed before the host runner starts Codex.
• Job files are local, owner-only runtime data and are never uploaded by this project.
• Installation backs up the MCP JSON and changes only the named openai-codex entry.
• A release-blocking scanner checks for tokens, private keys, email addresses, local home paths, and Claude Science organization IDs.

Read SECURITY.md for the trust boundaries and ARCHITECTURE.md for the job state model.

Troubleshooting

Start with:

claude-science-codex-doctor

Exact errors, including UnknownIssuer, stale queued jobs, a missing codex-code-mode-host, missing final messages, and requested/actual model differences, are covered in TROUBLESHOOTING.md.

Uninstall

./uninstall.sh

This preserves prior MCP backups and local job history. To remove the integration and its job data:

./uninstall.sh --purge-data

Development

The runtime has no npm dependencies.

npm test
npm run test:slow
npm run security

The default suite uses a fake Codex executable and requires no network credentials. The slow suite proves a job longer than 60 seconds survives after the submitting MCP process exits.

License

MIT