# 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.

```mermaid
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

```bash
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:

```bash
claude-science-codex-doctor
```

See the [Chinese quick start](docs/QUICKSTART.zh-CN.md) 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](docs/SECURITY.md) for the trust boundaries and [ARCHITECTURE.md](docs/ARCHITECTURE.md) for the job state model.

## Troubleshooting

Start with:

```bash
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](docs/TROUBLESHOOTING.md).

## Uninstall

```bash
./uninstall.sh
```

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

```bash
./uninstall.sh --purge-data
```

## Development

The runtime has no npm dependencies.

```bash
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