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, authenticated locally
• Linux, macOS, or Windows through WSL

Check Claude before installation:

claude --version
claude auth status

Install from GitHub

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

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:

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:

{
  "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

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.

License

MIT. See LICENSE.