review-loop

A Claude Code plugin that adds an automated code review loop to your workflow.

What it does

When you use /review-loop, the plugin creates a two-phase lifecycle:

1. Task phase: You describe a task, Claude implements it
2. Review phase: When Claude finishes, the stop hook prepares a Codex runner script and blocks exit. Claude then runs Codex directly (with output streaming to the user) and addresses the review feedback.

The result: every task gets an independent second opinion before you accept the changes, and you can watch the review happen in real time.

Review coverage

The plugin spawns up to 4 parallel Codex sub-agents, depending on project type:

After all agents finish, Codex deduplicates findings and writes a single consolidated review to reviews/review-<id>.md.

Requirements

• Claude Code (CLI)
• jq — brew install jq (macOS) / apt install jq (Linux)
• Codex CLI — npm install -g @openai/codex

Codex multi-agent

This plugin uses Codex multi-agent to run parallel review agents. The /review-loop command automatically enables it in ~/.codex/config.toml on first use.

To set it up manually instead:

# ~/.codex/config.toml
[features]
multi_agent = true

Installation

From the CLI:

claude plugin marketplace add hamelsmu/claude-review-loop
claude plugin install review-loop@hamel-review

Or from within a Claude Code session:

/plugin marketplace add hamelsmu/claude-review-loop
/plugin install review-loop@hamel-review

Updating

claude plugin marketplace update hamel-review
claude plugin update review-loop@hamel-review

Usage

Start a review loop

/review-loop Add user authentication with JWT tokens and test coverage

Claude will implement the task. When it finishes, the stop hook:

1. Prepares a Codex runner script and prompt file
2. Blocks Claude's exit with instructions to run the review
3. Claude runs bash .claude/review-loop-run-codex.sh — Codex output streams to the user
4. Codex writes findings to reviews/review-<id>.md
5. Claude reads the review, addresses items it agrees with, then stops

Cancel a review loop

/cancel-review

How it works

The plugin uses a Stop hook — Claude Code's mechanism for intercepting agent exit. When Claude tries to stop:

1. The hook reads the state file (.claude/review-loop.local.md)
2. If in task phase: writes a runner script and prompt file, transitions to addressing, blocks exit with instructions for Claude to run Codex
3. If in addressing phase: allows exit and cleans up

State is tracked in .claude/review-loop.local.md (add to .gitignore). Reviews are written to reviews/review-<id>.md.

File structure

claude-review-loop/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── commands/
│   ├── review-loop.md        # /review-loop slash command
│   └── cancel-review.md      # /cancel-review slash command
├── hooks/
│   ├── hooks.json            # Stop hook registration (30s timeout)
│   └── stop-hook.sh          # Core lifecycle engine
├── scripts/
│   └── setup-review-loop.sh  # Argument parsing, state file creation
├── AGENTS.md                  # Agent operating guidelines
├── CLAUDE.md                  # Symlink to AGENTS.md
└── README.md

Configuration

The stop hook timeout is set to 30 seconds in hooks/hooks.json. The hook itself is fast (it only writes files and returns a block decision); Codex runs separately via Claude's Bash tool.

Environment variables

Telemetry

Execution logs are written to .claude/review-loop.log with timestamps, codex exit codes, and elapsed times. This file is gitignored.

Credits

Inspired by the Ralph Wiggum plugin and Ryan Carson's compound engineering loop.