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. Runs are efficient by default (every sandbox, no permission-probe PASS required); --strict or "safety_mode": "strict" in the operator profile adds the probe gate. 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 only: every entry refuses another host (paired-session needs macOS; Linux and other hosts are not supported).
• 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. 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.