gauntlet-loop-codex

Gauntlet Loop for Codex

A Codex-native builder-critic loop that improves real artifacts against a frozen quality bar until a fresh blind critic prefers ours.

This is an independent Codex adaptation of RoboNuggets' Gauntlet Loop. It replaces Claude-specific loop commands with native Codex subagents, verifiable state, deterministic gates, and resumable progress.

What it does

• Runs the work directly or produces a short paste-ready handoff prompt.
• Compares against a named, fetchable, directly comparable reference.
• Keeps builders separate from fresh-context, read-only critics.
• Uses identity-scrubbed A/B artifacts and binary verdicts instead of drifting scores.
• Persists a resumable run ledger outside the working repository.
• Requires deterministic gates and a final whole-artifact win before completion.
• Rejects stale artifacts, changed reference captures, weak evidence, ties, and invalid comparisons.

Requirements

• Codex with subagent support.
• Python 3.10 or newer; the scripts use only the standard library.
• The tools needed to fetch and inspect the chosen reference, such as web access, a browser, rendering, tests, or benchmarks.

Install

With Codex

Ask Codex:

Use $skill-installer to install the skill from https://github.com/thors-github/gauntlet-loop-codex/tree/main/.agents/skills/gauntlet-loop

Manually for your user

Copy .agents/skills/gauntlet-loop to:

<CODEX_HOME>/skills/gauntlet-loop

When CODEX_HOME is unset, the common Codex fallback is ~/.codex/skills/gauntlet-loop.

Inside one repository

Copy the skill folder to the target repository:

<target-repository>/.agents/skills/gauntlet-loop

Codex normally detects skill changes automatically. Restart Codex if the skill does not appear.

Use

Run the loop directly:

$gauntlet-loop improve README.md until it beats <named reference URL>

Generate only a handoff prompt:

$gauntlet-loop make a paste-ready gauntlet prompt for a beginner-friendly API guide using <named guide> as the bar

Resume a previous run:

$gauntlet-loop resume the latest run for this workspace

If no bar is supplied, the skill proposes two or three named candidates and waits for the user's choice. A valid bar must be named, fetchable, and directly comparable. Remote references are captured locally before judging so their content and integrity can be verified throughout the run.

How it works

1. Freeze the reference, define the binary judge question, and declare deterministic gates.
2. Capture a baseline and split the goal into independently judgeable pieces.
3. Delegate focused improvements to builders and equivalent A/B comparisons to fresh critics.
4. Record every decoded verdict, artifact hash, gate result, and next gap in a resumable ledger.
5. Finish only after a fresh final critic prefers ours, all gates pass, and the judged artifacts remain unchanged.

See the full skill instructions and critic contract.

Reference files and artifacts are treated as untrusted data. The skill does not execute third-party code, binaries, macros, or active content without explicit user authorization and safe isolation.

Validate

Windows:

py -3 .agents/skills/gauntlet-loop/scripts/gauntlet_state.py self-test

macOS or Linux:

python3 .agents/skills/gauntlet-loop/scripts/gauntlet_state.py self-test

The self-test covers initialization, standard SHA-256 integrity, invalid sources, traversal-like run IDs, failed gates, candidate and reference drift, valid completion, and stop/resume behavior.

Credits and license

This is an independent Codex adaptation of Gauntlet Loop, created by Jay E / RoboNuggets. The technique and original prompt are credited to Matt Shumer.

Licensed under CC BY 4.0. See NOTICE.md for source, modification, disclaimer, and attribution details.