review-loop Guide

What review-loop Does in Codex

A review-loop request goes to the Codex review-loop skill, which resolves the entry key in .review-loop/config.md and hands the work item to the Codex paired-session skill. That skill runs the coordinator through plan, implementation and review. With lifecycle on, finish, polish, docs and security follow, up to DONE. With lifecycle off, it stops after the gate; acceptance returns the uncommitted tree. It accepts only on your explicit acceptance. A request to review existing code hands off the same way as run --review-only, and an existing plan becomes the work item (PLAN drafts and reviews it again). entry: legacy, asking for "the legacy review-loop workflow" and resuming a legacy session are refused, and a failed check before the coordinator starts refuses instead of falling back. Every run uses one mode (every sandbox, no permission probe: permission-probe and strict mode were removed in v3.7.0; --strict only prints a NOTE). The legacy workflow was removed in v2.13.0 (routing) and v2.13.1 (the Codex plan and execute skills, the Codex Stage 1 workflow and its agents). Legacy session files under .review-loop/sessions/ are left on disk and never read. Details: docs/paired-session-migration.md.

A request to review a pull request ("review PR 123", a PR URL), a branch or ref goes to the Codex review-pr skill, which runs the paired-session report mode (entry: legacy and asking for the legacy review-pr are refused): it reviews it in a temporary clone with no tests unless you confirm one, writes review-report.md, and fixes, commits or posts nothing; posting is a separate request with a secret scan and a second confirmation of the full body. simplify is not available there (Claude Code: run /review-loop:code-quality-loop on the change (its POLISH-Q simplifier)).

Skills in Codex

• review-loop, paired-session, review-pr
• guide

Not on Codex:

• code-quality-loop (ask review-loop to review an existing change instead: a review-only run with the quality writers on)
• reorganize

Usage Notes

• The entry skills load their instructions via docs/protocol/loading.md and scripts/read_protocol.py, shared with Claude Code.
• Codex loads the skills from the installed plugin (codex plugin add review-loop@review-loop-marketplace, see docs/install-codex.md), not from the workspace.
• macOS and native Windows: every entry refuses another host (paired-session needs macOS or native Windows; Linux (WSL included) and other hosts are not supported). On Windows --detach is refused, Git for Windows (Git Bash) is required, and run directories and workspaces stay out of OneDrive-synced folders. On Windows the Codex skills run their commands in PowerShell as best effort; the Claude Code entry is the tested Windows path.
• Hard caps — blocking PLAN/EXEC reviews HOLD at the cap; resume --add-rounds N (1-10) continues the run. Eligible advisory-only reviews get one repair attempt per phase, then advisory acceptance, or exit at the cap without an attempt. Writer replay takes the advisory exit at any round and preserves the attempt. Blocking rounds preserve it; send-back grants a new EXEC attempt. EXEC needs a passed configured test, own run evidence and the current tree. See the advisory rules for open ledger rows.
• Keep the shared review-loop config in .review-loop/config.md; roles and models come from the paired-session operator profile; gemini (Antigravity CLI agy) is an optional third vendor for the reviewer and the gate (README.md, Configuration). Which config keys apply (round limits, docs_file, skip_quality_polish, review_focus, review_style, quality_focus, handsfree, and auto_commit on a review-only run) is listed in docs/protocol/paired-session-entry.md (Profile and settings).
• A review of existing code is a review-only run. With lifecycle on, accept normally makes one local commit (never a push); auto_commit: false in .review-loop/config.md keeps the accepted change uncommitted. Lifecycle off stops after the gate; acceptance returns the uncommitted tree.

Troubleshooting

• The skills are missing right after an install. A fresh Codex session is what loads the plugin's skills. Start a fresh Codex session after installation (docs/install-codex.md).
• A slash command does nothing (Unrecognized command). Slash commands such as /review-loop:paired-session are Claude Code only; Codex matches skills by their description, in natural language only. Ask in plain words, for example "run review-loop on this branch", "review PR 123" or "use paired-session for this task".
• --detach is refused on Windows. A headless session is not supported there. Drop the flag and use an interactive session.
• An entry refuses with paired-session needs macOS or native Windows. Linux (WSL included) is not supported. Run from macOS or native Windows.