inspectrum

<div align="center">

# Inspectrum

### Catch the bad plan before your agent spends the tokens.

[![CI](https://github.com/yannmenec/inspectrum/actions/workflows/ci.yml/badge.svg)](https://github.com/yannmenec/inspectrum/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/inspectrum.svg)](https://www.npmjs.com/package/inspectrum)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node >= 20](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](https://nodejs.org/)

**Claude plans it. GPT reviews it. You approve it.**

</div>

---

Every AI coding disaster starts the same way: a plausible plan, approved in three seconds.

The problem isn't that your agent plans badly — it's that **nobody checks the plan**. You skim it, hit approve, and find out 40 minutes and 200k tokens later that step 2 was wrong. Asking the same model to review its own plan doesn't help: same model, same blind spots, same miss — twice.

**Inspectrum wires a rival LLM into your agent's plan mode.** When Claude Code finishes a plan, Codex (GPT) reviews it *before* the approval dialog reaches you. Findings bounce the plan back to Claude for revision — so the plan you finally approve has already survived a second opinion. (And if the reviewer can't run, the plan passes through with a warning, never blocked.)

## When a skill is enough

For an occasional second opinion, a rule can tell one agent to call another and compare the replies. That is a reasonable lightweight option.

Inspectrum is for the repeatable checkpoint. In Claude Code, the plugin runs at the plan-to-execution boundary without relying on a remembered prompt, caps revision loops, and fails open on operational errors. Other local MCP hosts can call the same `review_plan` contract on demand. Both paths keep findings attributed, return a common verdict shape, preserve human control, and write local evidence for successful reviews.

Recreating those guarantees with a skill means maintaining the orchestration, output validation, health checks, failure policy, and session record yourself.

## Quick start

You need [Node 20+](https://nodejs.org), Claude Code, and Codex CLI >= 0.99.0 authenticated with a [ChatGPT subscription](https://chatgpt.com/pricing) (no API key):

```bash
claude plugin marketplace add yannmenec/inspectrum
claude plugin install inspectrum@inspectrum
```

That's the whole install. Next time you finish a plan in plan mode:

```text
⏺ ExitPlanMode
  ⎿  inspectrum×codex: REVISE (round 1/2)          # abridged — real output
     Majors:                                       # adds a full-report path
     - [codex] Migration drops the unique index before backfilling —
       concurrent writes can insert duplicates.
       Fix: backfill first, drop the index last.
     Revise the plan to address these findings, then finish the plan again.

⏺ ExitPlanMode
  ⎿  inspectrum: codex approved the plan (session 2026-07-12…).
     ┌ Ready to code? ────────────────
     │ Here is Claude's plan…        ← your normal approval dialog
```

No prompt to remember, no button, zero tokens spent on triggering. The gate is a deterministic hook — it fires on every plan, whether your session runs Fable, Sonnet, or Haiku. Two commands give you the automatic gate; the on-demand `/inspectrum:review` command needs one extra line (registering the MCP server — shown in the assisted setup below).

<details>
<summary>Prefer the agent to install and check everything for you? Paste this into Claude Code.</summary>

````text
Set up inspectrum's Codex plan gate. Use normal approvals only — do not
switch to Bypass Permissions or Full Access.

Steps:
1. Run `node --version`. If < 20, stop and tell me to install Node 20+
   from https://nodejs.org first.
2. Run `codex --version`. If it is missing or older than 0.99.0, run
   `npm install -g @openai/codex@latest` and verify again.
3. Run `claude plugin marketplace add yannmenec/inspectrum`, then
   `claude plugin install inspectrum@inspectrum`.
4. Run `claude mcp add --transport stdio --scope user inspectrum -- npx -y inspectrum@latest`
   (this powers the on-demand /inspectrum:review command).
5. Run `npx -y inspectrum@latest doctor` and show me the output,
   including the resolved codex model/effort lines.
6. Run `codex login status`.
   - If it prints "Logged in", tell me: "✅ Setup complete. Your next
     plan-mode plan gets a Codex review automatically." Done.
   - Otherwise (not logged in), pop open a Terminal window with codex
     already running by executing:
       `osascript -e 'tell application "Terminal" to do script "codex"'`
     Then tell me: "A Terminal window opened with codex running.
     Inside that window, click 'Sign in with ChatGPT', complete the
     login in my browser, then close the Terminal window. inspectrum
     is then ready."

Do NOT use sudo, edit shell profiles, push git changes, read .env or
credentials, or publish packages. Report back: Node version, codex
install status, doctor verdict, and whether login was needed.
````

</details>

## How it works

```
you ──▶ Claude Code ──▶ plan ready ──▶ ExitPlanMode
                                          │
                              inspectrum plan-gate (hook)
                                          │
                              Codex reviews the plan
                              (read-only sandbox, your ChatGPT sub)
                                          │
                    ┌─────────────────────┴──────────────────────┐
              APPROVE ✅                                REVISE / REJECT ❌
                    │                                             │
        your approval dialog                    findings go back to Claude,
        appears as usual                        it revises, gate runs again
                                                       (max 2 rounds)
```

Built to be **boring and safe**:

- **Fails open.** Codex not installed, logged out, timed out, network down — the plan proceeds with a visible warning. Operational errors don't block your work; the gate degrades, it doesn't brick.
- **Never auto-approves.** A green review still lands on *your* approval dialog. The gate can delay it (while Claude revises) but can never click it — you keep the final call.
- **No wasted reviews.** Within a session, an unchanged plan is hash-cached and not re-reviewed; only real revisions spend a round.
- **Read-only reviewer.** Codex runs in a pinned read-only sandbox (`codex exec -s read-only --ephemeral`), and sandbox-weakening flags in your config are stripped. The reviewer reads; it doesn't write.
- **Kill switch.** `[plan_gate] enabled = false` in `~/.inspectrum/config.toml`, or disable the plugin per project.

## Why a rival model?

- **Plans are leverage.** A flaw caught at plan time costs a paragraph. The same flaw caught at PR time costs a rewrite.
- **Self-review is an echo chamber.** The model that wrote the plan is the least qualified to find its blind spots.
- **Claude and GPT disagree usefully.** Different training, different failure modes, different objections. That disagreement is the product.
- **Use an existing subscription.** No separate API bill when using your ChatGPT subscription; reviews consume your existing Codex subscription allowance. API-key backends are billed by their provider.

## What's in the box

| | |
|---|---|
| 🚦 **Plan gate** | Every Claude Code plan reviewed by Codex before it reaches you — automatic, max 2 revision rounds |
| 🔍 **On-demand review** | `/inspectrum:review` or "Review this plan with inspectrum" from any MCP host |
| 🧑‍⚖️ **Multi-reviewer + judge** | Run codex + gemini + claude in parallel; a judge consolidates into one verdict |
| 📋 **One verdict** | `approve / revise / reject` + findings by severity, with reviewer attribution |
| 🗂️ **Session logs** | Markdown record of every review — verdict, findings, revised plan — under `~/.inspectrum/sessions/` (0700 perms) |
| 🩺 **`inspectrum doctor`** | One command to check your reviewer is installed, authenticated, and resolving the right model — fails loudly if Codex is logged out |

## Works with

| Your agent | Your reviewer | Setup |
|------------|--------------|-------|
| **Claude Code** | Codex (GPT) | Plugin — 2 commands above |
| **Codex app / CLI** | Claude | `codex mcp add inspectrum -- npx -y inspectrum@latest` + config below |
| **Claude Desktop** (macOS) | Codex (GPT) | Download [`inspectrum-0.2.2.mcpb`](https://github.com/yannmenec/inspectrum/releases/download/v0.2.2/inspectrum-0.2.2.mcpb), open, confirm. The earlier v0.2.0 bundle was incomplete — use the v0.2.2 asset, not npm/stdio. |
| **Cursor** | Codex (GPT) | [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](https://cursor.com/en/install-mcp?name=inspectrum&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImluc3BlY3RydW1AbGF0ZXN0Il19) |

<details>
<summary><b>Codex app / CLI setup</b> — use Claude as your reviewer</summary>

Paste this into the Codex app or CLI:

````text
Set up inspectrum so I can review my plans with Claude. Use normal
approvals only.

Steps:
1. Run `node --version`. If < 20, stop and tell me to install Node 20+
   from https://nodejs.org first.
2. Run `claude --version`. If "command not found", run
   `npm install -g @anthropic-ai/claude-code` and verify again.
3. If `~/.inspectrum/config.toml` does not exist, create it with:

   [defaults]
   reviewers = ["claude"]

4. Run `codex mcp add inspectrum -- npx -y inspectrum@latest`
5. Run `npx -y inspectrum@latest doctor` and show me the output.
6. Pop open a Terminal window with claude already running so I can
   confirm or complete login, by executing:
     `osascript -e 'tell application "Terminal" to do script "claude"'`
   Then tell me:
   - "If claude shows its chat prompt, you're already logged in —
     close the Terminal window. inspectrum is ready."
   - "If claude shows /login or opens a browser, complete the sign-in
     with your Claude acc