# Claude Reviewer for Codex

Use Claude as an independent second-model reviewer from inside Codex.

Claude Reviewer gives Codex a managed review workflow instead of a brittle one-off `claude -p`
shell command. Reviews run in fresh Claude sessions against disposable Git snapshots, so Claude can
inspect surrounding code and run focused tests without changing your real checkout.

> Independent open-source project. Not affiliated with or endorsed by Anthropic or OpenAI.

## Features

- Normal and adversarial reviews
- Exact commit review that ignores unrelated dirty files
- Working-tree, branch, automatic, and explicit-file scopes
- Disposable snapshots where diagnostic tests may safely write artifacts
- Structured findings with severity, file, lines, evidence, and recommendations
- Background jobs with durable status, results, cancellation, and desktop notifications
- Wait mode that returns the final review through one blocking wait call without polling
- Stale-result detection when source work changes after launch
- Per-review model, effort, and quality profiles
- No runtime npm dependencies

## Requirements

- Codex with plugin support
- Git
- Node.js 20 or newer
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), authenticated locally
- Linux, macOS, or Windows through WSL

Check Claude before installation:

```bash
claude --version
claude auth status
```

## Install from GitHub

Add this repository as a Codex marketplace and install the plugin:

```bash
codex plugin marketplace add adsorce/claude-reviewer-for-codex
codex plugin add claude-reviewer@claude-reviewer
```

Start a new Codex session after installation so the skill and MCP tools are loaded.

You can also open `/plugins` in Codex, select the **Claude Reviewer** marketplace, and install the
plugin there.

## Usage

Ask naturally:

```text
Have Claude adversarially review my current changes in the background.
Ask Claude to review commit 9f2c1ab only.
Have Claude review this branch against main and wait for the result.
Ask Claude to pressure-test docs/SPEC-payments.md.
Use Claude Opus at max effort to review commit 9f2c1ab.
Run a balanced Claude review against main.
Show me the result of the background Claude review.
```

### Background completion

Background mode returns a job ID immediately and persists the result. The broker emits a
best-effort desktop or terminal notification when Claude finishes. Codex currently has no
documented plugin API that can spontaneously resume a model turn after a tool call has returned, so
the plugin does not secretly launch another Codex session. Use wait mode when the current Codex turn
must consume the review before continuing. Start always returns a job ID first; Codex then makes one
blocking wait call, which preserves recovery and cancellation if that wait is interrupted.

Normal tool output is deliberately concise: review kind, model, effort, target, elapsed time, job
ID, verdict, and findings. The full Claude `stream-json` transcript stays in the job log and is only
returned when `include_raw=true` is explicitly requested for debugging.

During a wait call the MCP server emits progress notifications with the current phase and elapsed
seconds. Codex clients that render MCP progress can show those updates directly in the tool card;
clients that do not still show the normal elapsed time for the single wait call.

### Exact commit scope

Supplying a commit checks out that commit in the disposable snapshot and compares it only with its
parent. The source checkout's staged, unstaged, and untracked files are excluded. Merge commits need
an explicit parent because each parent produces a different review target.

### Model and effort

The built-in default is `thorough`, which resolves to the rolling `opus` alias at `high` effort.
The aliases follow the user's installed Claude Code version rather than pinning an aging dated model
ID.

| Profile | Model | Effort | Intended use |
|---|---|---|---|
| `thorough` | `opus` | `high` | Shipping and adversarial review |
| `balanced` | `sonnet` | `high` | Routine code review |
| `economy` | `sonnet` | `medium` | Smaller, cost-sensitive checks |
| `inherit` | Claude CLI default | Claude CLI default | Follow local Claude configuration |

Claude Fable is also supported as an explicit model, for example `model=fable` with `effort=high`.
It is intentionally not a built-in profile because Fable availability and billing may differ from
the normal Claude subscription path. The portable default remains Opus at high effort.

Any review may override `model` and `effort` independently. Persistent defaults may be placed in
`~/.config/claude-reviewer/config.json` or `.claude-reviewer.json` at the repository root:

```json
{
  "profile": "balanced"
}
```

Per-review values take precedence, followed by user configuration, repository configuration, and
the built-in default. Every job records the resolved profile, model, effort, and configuration
sources.

## Safety model

The original checkout is used only to resolve Git state and construct a disposable snapshot. Claude
runs with that snapshot as its working directory. Edit and write tools are disabled, but shell
commands are available so the reviewer can run tests and investigate suspicions.

Snapshot Git objects are copied rather than shared or hard-linked, and the local source remote is
removed before Claude starts. The reviewer also receives a reduced environment instead of every
repository-specific variable from the invoking shell.

Ignored files, including typical local secret files, are not copied. Tests that depend on ignored
virtual environments or dependency directories may be unable to run; Claude must report that as
unverified rather than claiming a pass.

The disposable snapshot is the primary cross-platform protection against accidental changes. v0.1
does not claim a hostile-code OS sandbox. Review commands can execute repository code, so use the
plugin only in repositories you trust.

Native Windows is not supported in v0.1 because the plugin cannot yet guarantee process-tree
cancellation or PID identity there. WSL uses the tested Linux path. Setup fails explicitly on native
Windows instead of silently offering weaker cancellation.

## Development

```bash
npm test
npm run check
python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/claude-reviewer
```

The test suite uses temporary Git repositories and fake Claude executables; it does not consume
Claude usage.

Design and acceptance criteria are in [docs/SPEC-v0.1.md](docs/SPEC-v0.1.md).

## License

MIT. See [LICENSE](LICENSE).