codex-loop

codex-loop

A Claude Code plugin that uses Codex CLI as a critic-only reviewer for plans and code, looping write → review → rewrite until convergence or a user-set round cap.

What it does

Command	What it does
/codex-plan-review <plan-path>	One-shot Codex review of a plan file. Returns structured critique.
/codex-code-review [<scope>]	One-shot Codex review of a git diff (default: branch vs origin/main).
/codex-plan "<task>"	Drafts a plan with neo+Linus, loops with Codex review until clean, gates with user. Saves to docs/plans/.
/codex-implement <plan-path>	Implements a converged plan, loops with Codex code review, gates on the final diff.
/codex-build "<task>"	One-shot omnibus: plan loop (no mid-gate) → implement loop → final-diff gate.

Codex never writes files in this system. It emits structured critique only. Claude (with help from neo:neo, Linus, and CompliantImplementer subagents) does all writing.

Prerequisites

• Claude Code (recent version)
• Codex CLI: npm i -g @openai/codex-cli then codex login
• git, jq, bash on PATH
• Optional but recommended: neo:neo plugin, Linus and CompliantImplementer agents in ~/.claude/agents/

Install

# From a private git URL (recommended for internal teams):
/plugin install <git-url-of-this-repo>

# Verify
ls ~/.claude/plugins/cache/*/codex-loop/*/  # should show .claude-plugin/, commands/, lib/, etc.

After install, run any looper once — it will seed ~/.claude/codex-loop/config.json from the bundled default.

Configuration

Edit ~/.claude/codex-loop/config.json:

{
  "default_rounds": 4,
  "codex_model": null,
  "plans_subdir": "docs/plans",
  "max_codex_tokens": 200000,
  "codex_exec_timeout_seconds": 300
}

Or override per-invocation: --rounds 6, --codex-model gpt-5.

Round cap behavior

If Codex still emits NEEDS_CHANGES after the cap, the looper stops integrating, prints the final critique, and surfaces to you. Your options: approve as-is, request more rounds, hand-edit, or abandon.

Drift and flapping safeguards

• If a single round rewrites >50% of the artifact, the looper warns before continuing.
• If round N+1's issues overlap with round N's, the looper warns about possible flapping.

Resuming an interrupted run

The looper checkpoints state to ~/.claude/codex-loop/state/<slug>.json after every round. Re-running /codex-plan "<same-task>" (or with --resume <slug>) detects the state and offers to resume.

Testing the parser

cd <plugin-cache-path>
bash scripts/test-parser.sh

Expected: all tests pass.

Architecture

See docs/superpowers/specs/2026-05-06-codex-loop-design.md in the source repo for the full design.

License

MIT