looprinter

A loop template for building iterative agent harnesses. Copy loop.sh, edit the prompts, run it.

Core Concepts

1. Ralph Loop

while true:
    Plan → Build → Verify → (fail? re-plan) → ... → Done

Each iteration starts a fresh agent with a clean context window. State lives in the filesystem, not in the agent's memory. All phases — prompts, verification gates, post-processing — live in a single .sh file.

2. Headless Agent Execution

The loop runs agents in headless mode (codex exec, claude -p) from inside a main Claude Code session. The main agent spawns background loops as tasks or cronjobs. This means:

• The loop runs autonomously — no human in the loop
• The main agent stays free to observe, analyze, and intervene
• Multiple loops can run in parallel on different tasks

3. Working Records

Every agent iteration appends to a working record (JSONL in working-records/). Records capture what the agent attempted, what failed, and what changed. The agent's context window is disposable — the working record is not.

4. Cronjob-Driven Double Loop

The main agent reads working-records/ from background loops, then improves the harness itself:

┌─────────────────────────────────────────────┐
│  Main Agent (Claude Code session)           │
│                                             │
│  reads working-records/ ──► edits loop.sh   │
│       ▲                         │           │
│       │                         ▼           │
│  ┌────┴────────────────────────────────┐    │
│  │  Background Loop (cronjob/task)     │    │
│  │  Plan → Build → Verify → re-plan    │    │
│  │       │                             │    │
│  │       └──► writes working-records/  │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

5. Exact Cycle Contract

loop.sh enforces a strict cycle order:

1. setup() runs once, then the cycle starts.
2. Plan runs when output/plan.json is missing or when all tasks are already complete.
3. Build runs and repeatedly executes exactly one task per iteration.
4. Verify checks required artifacts and schema invariants.
5. On verify fail, the loop archives output/plan.json as working-records/plan_cycle_<N>.json, removes it, then re-plans next cycle with errors.
6. On verify pass, configured post-phases run and then the loop exits.

The build contract is one-task-per-iteration:

• read output/plan.json and output/progress.txt first
• execute the first remaining task where passes is false
• mark that single task as passes: true
• append cumulative findings to output/progress.txt
• finish the build iteration

Structure

loop.sh                              — self-contained loop template (prompts + engine in one file)
working-records/                     — JSONL logs from loop iterations (gitignored)
output/                              — runtime artifacts produced by the loop (gitignored)
.claude/skills/looprinter-interview/ — interactive harness configuration skill
.claude/skills/looprinter-executor/  — loop execution and monitoring skill

Artifact Contract

• output/plan.json — object containing tasks array; each task has id, title, description, targetFile, passes, and notes.
• output/progress.txt — cumulative findings and notes; must be non-empty for verify().
• working-records/*.jsonl — line-delimited records for each phase/output cycle.
• working-records/plan_cycle_*.json — archived snapshots of output/plan.json when verify fails.

Usage

Two skills drive the workflow from a main Claude Code session:

1. /looprinter-interview — interview the user, then write prompt functions and the verify() gate into loop.sh.
2. /looprinter-executor — launch loop.sh as a cronjob, monitor output/progress.txt and working-records/, intervene by editing prompt functions when failures repeat, and stop the cron when done.

Always run the loop through /looprinter-executor from a Claude Code session. Foreground execution blocks the session and breaks the double-loop pattern (the main agent can no longer observe working-records/ or improve the harness).

Direct shell invocation exists only for debugging the harness itself outside a Claude Code session:

./loop.sh codex 50
./loop.sh codex-spark
./loop.sh claude 30

Porting to Another Project

To use looprinter in a different project, copy these two paths into the target project root:

loop.sh
.claude/skills/looprinter-executor/

Optionally also copy .claude/skills/looprinter-interview/ if you want the interactive harness configurator in that project.

Once copied, no edits to the target project's CLAUDE.md are required — both skills self-register via Claude Code's skill discovery and trigger on phrases like "run the loop", "execute", or "configure the loop". The first time you run /looprinter-interview in the new project, it writes the project-specific prompt functions and verify() gate into the copied loop.sh.

Make sure loop.sh is executable (chmod +x loop.sh) and that the project's .gitignore excludes output/ and working-records/.

Building a New Harness

Use the /looprinter-interview skill to interactively configure a harness — it interviews you about your objective, then generates the prompt functions and verify() gate directly into loop.sh.

Or manually copy loop.sh and edit the functions:

• gen_plan_prompt() — what the planning agent should do
• gen_build_prompt() — what the build agent should do per task
• gen_replan_prompt() — how to recover from verification failure
• verify() — quality gates (exit 0 = pass)
• setup() — one-time preprocessing before the loop
• POST_PHASES + gen_<name>_prompt() — optional phases after verify passes