check-loop

Codex reviews your plans, research and code.A Claude Code and pi plugin. Only findings with verified evidence block.

Claude Code 2.1.257+piReviewed by CodexMIT license

Quick start

1npm install -g @openai/codex && codex loginshell

2/plugin marketplace add Novacon/check-loopclaude code

3/plugin install check-loop@lordknows13-check-loopclaude code

4/check-loop path/to/plan.mdclaude code

No API key. It uses your Codex login.

01 / What you get 4 skills

what you get

Your session model is the orchestrator. It runs the workflow and opens every cited source before acting on a finding. Codex reviews in a read-only sandbox.

Plan

Review a plan

One broad review, then later rounds check only the fixes. Six rounds by default, or one pass with --quick. Picks up where it left off if interrupted.

claude code

/check-loop path/to/plan.md

Research

Research a question

Writes a sourced draft and Codex checks it. You get one Markdown report with sources and open questions. No code.

claude code

/check-loop:research "question"

Execute

Execute a plan

The runner snapshots the tree before each step, without staging. A fresh subagent builds the step, your checks run, and Codex reviews the diff since the snapshot. A step gets three fix attempts. Nothing is committed or pushed without your approval.

claude code

/check-loop:execute path/to/plan.md

Settings

Pick the reviewer

Set the Codex model, effort, round limit and implementer model, for all projects or just one. Unset values use your Codex and session defaults.

claude code

/check-loop:settings

02 / How it decides One finding

how it decides

Every finding cites a source and carries an evidence label. Only findings the orchestrator has verified can block.

InCodex raises a finding

01 The orchestrator checks the citation

VERIFIED, critical or importantBlocks: accept, reject or counter

INFERENCE or UNVERIFIEDReport only

Minor, or a questionReport only

02 The next round diff only

Regression, or a missed critical defectCan still block

Repeat of a decided findingDropped

evidence labels

VERIFIED    the cited source supports the claim
INFERENCE   suggested by the source, not reproduced
UNVERIFIED  evidence missing or inaccessible

A failure is never approval

A failed, empty or timed-out review is retried once, then the run stops. If blockers stall or the round limit is reached, you decide what happens next.

Secrets are redacted from everything Codex is sent, and step reviews omit .env, secret and credential files. Codex can still read the checkout, so keep secrets in ignored paths.

1broad review, then diffs only

6rounds by default, 1 to 40

1dispute per rejected finding

20minreviewer timeout per turn

03 / Install 4 steps

install it

You need Node.js 18+ and a signed-in Codex CLI. For pi, see the quick start.

STEP 1

Check your version

Claude Code 2.1.257 or later.

shell

claude --version

STEP 2

Sign in to Codex

Headless? Use codex login --device-auth.

shell

npm install -g @openai/codex
codex login

STEP 3

Install the plugin

Inside Claude Code.

claude code

/plugin marketplace add Novacon/check-loop
/plugin install check-loop@lordknows13-check-loop
/reload-plugins

STEP 4

Pick your model

The skills don't switch models, so start on the one you want.

shell

claude --model fable

Status: ready

codex-invoke.mjs setup confirms Codex is installed and signed in, not model access.

Wrong reviewer

Unsupported or mismatched settings fail. It never swaps reviewers silently.

Uncommitted work

execute asks first: use a separate worktree, or include your changes.

Update

/plugin marketplace update lordknows13-check-loop, then /plugin update check-loop@lordknows13-check-loop. Settings carry over.

04 / Settings /check-loop:settings

tune it

Each setting uses the first value it finds: CLI flag, then .claude/check-loop.json, then ~/.claude/check-loop/config.json, then the default.

Setting	Default	What it changes
`model`	your Codex config	Codex reviewer model ID, or `default`.
`effort`	your Codex config	Reviewer reasoning effort, or `default`.
`maxRounds`	6	Plan and research round limit, 1 to 40.
`implementerModel`	your session model	Subagent model for `execute`, such as `opus` or a pi `provider/id`.

From the CLI

node plugins/check-loop/scripts/codex-invoke.mjs config --project --effort high

What's new in 5.2

Execution review runs in code, one codex app-server per command instead of a shared broker, and the scripts are less than half their old size.

Develop

The loop lives in scripts/lib/review-loop.mjs. node --test tests/ runs without model access.

GitHub README