Review

AI code review that actually closes the loop. 🛠️

@ppucc/review is a developer-first CLI for running serious AI review passes on your branch: isolated sandbox, structured findings, verified fixes, re-review, and a PR when the loop is done.

No copied prompt jungle. No half-baked "AI said maybe" comments. No yak-shaving ritual before every review.

Just:

pnpm add -D @ppucc/review
pnpm exec review init
pnpm review:build
pnpm review --base origin/main

That is the pitch. Four commands, one review pipeline. 🚀

Why Developers Like It

Most AI review tools stop at "here are some thoughts".

review keeps going:

• 🔍 Finds real issues across security, correctness, tests, and architecture.
• ✅ Verifies findings before treating them as work.
• 🧰 Fixes validated issues in an isolated branch.
• 🔁 Re-reviews the result for regressions and missed fixes.
• 📝 Opens a PR with a title/body generated from the actual run history.

It feels less like a chatbot and more like a tiny review shop living in your terminal.

The 30-Second Setup

Install:

pnpm add -D @ppucc/review

Initialize:

pnpm exec review init

Build the local runner:

pnpm review:build

Run it:

pnpm review --base origin/main

Need a quick health check?

pnpm exec review doctor

What It Feels Like

$ pnpm review --base origin/main

review  → starts an isolated Docker runner
review  → inspects your branch diff
review  → validates findings
review  → fixes what is actually valid
review  → re-reviews the result
review  → pushes review/run/<run-id>
review  → opens a GitHub PR

Tiny command. Big loop.

The Loop

flowchart LR
  A[Branch diff] --> B[Reviewer profiles]
  B --> C[Verifier]
  C --> D[Fixer]
  D --> E[Re-review]
  E --> F{Clean?}
  F -->|yes| G[PR]
  F -->|not yet| B

Under the hood, review run creates a run ledger under .context/review-runs/<run-id>/, runs the work in Docker, and keeps generated runtime artifacts out of your repository.

Bring Your Runner

Use Codex:

pnpm exec review init --runner codex
pnpm review --base origin/main

Use Claude Code:

pnpm exec review init --runner claude-code
pnpm review --base origin/main

Override the runner for one pass:

pnpm review --base origin/main --runner claude-code

Run Codex in fast mode:

pnpm review --base origin/main --fast

Package Manager Friendly

pnpm is the happy path:

pnpm add -D @ppucc/review
pnpm exec review init
pnpm review:build
pnpm review --base origin/main

npm works too:

npm install -D @ppucc/review
npm exec -- review init
npm run review:build
npm run review -- --base origin/main

Bun also gets a seat:

bun add -d @ppucc/review
bunx review init
bun run review:build
bun run review --base origin/main

What init Adds

review init detects your package manager, asks for the default runner, writes review.config.mjs, and adds the scripts you actually want:

{
  "review": "review run",
  "review:build": "review build-image",
  "review:clean": "review cleanup"
}

Prompts, review standards, and the Dockerfile stay inside the installed npm package. Your repo gets the small control surface, not a pile of generated runtime files.

Prefer setup without prompts?

pnpm exec review init --no-wizard --base origin/main --runner codex

Configuration

Start tiny:

export default {
  baseRef: "origin/main",
  runner: "codex",
};

Tune when you need to:

export default {
  baseRef: "origin/main",
  runner: "codex", // or "claude-code"
  imageName: "review:runner",
  packageManager: "pnpm",
  installCommand:
    "pnpm install --frozen-lockfile --ignore-scripts --prefer-offline --store-dir /.pnpm-store",
  model: "gpt-5.5",
  fastModel: "gpt-5.5",
  claudeModel: "claude-opus-4-6",
  fastServiceTier: "fast",
  codexCliVersion: "0.130.0",
  claudeCodeVersion: "latest",
  maxCycles: 12,
};

By default, packaged prompts and Docker assets resolve from node_modules/@ppucc/review. Override them only when your team wants to fork the review behavior.

Useful Commands

pnpm review --base origin/main
pnpm review --base origin/staging --cycles 4
pnpm review --base origin/main --brief docs/review-brief.md
pnpm review:build --dry-run
pnpm exec review doctor
pnpm review:clean --prune-ledgers

What Ships To npm

The package includes the things consumers need and skips the repo noise:

{
  "files": ["dist", "templates", "README.md", "LICENSE"]
}

That means the CLI, prompts, review standards, Dockerfile, README, and MIT license are all present in the published package.

Requirements

• Node.js 22+
• Docker
• Git
• Codex or Claude Code auth, depending on your selected runner
• GitHub CLI auth if you want automatic PR creation

Development

pnpm install
pnpm build
pnpm test
pnpm dev -- init
pnpm dev -- doctor
pnpm dev -- build-image --dry-run
pnpm dev -- run --base origin/main

Docs

• Review automation
• Review standards

License

MIT — see LICENSE.