loop-supervisor

Runs unattended sequential Claude iterations with fresh context and filesystem-based outcome classification.

2|Updated Feb 14, 2026
One-click install
npx skills add https://github.com/Gamaroff/agent-skills --skill loop-supervisor-gamaroff
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: loop-supervisor
Source: https://github.com/Gamaroff/agent-skills/tree/main/skills/loop-supervisor
Command: npx skills add https://github.com/Gamaroff/agent-skills --skill loop-supervisor-gamaroff

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Long unattended agent loops degrade in quality because each iteration re-invokes the same conversation, so late iterations work through a context consumed by earlier ones. This Skill moves the loop outside the session: a host process spawns one fresh claude -p per iteration and classifies each outcome from files on disk rather than from the assistant's prose. ## Core Features & Use Cases - Fresh-context iterations: Each loop iteration spawns a new Claude process with a pinned session id, so iteration 20 is as sharp as iteration 1, and every iteration stays reopenable with claude --resume. - Deterministic outcome classification: A pure classifier reads run-state files, pipeline locks, halt-file timestamps, and a git progress oracle to label each iteration progress, done, halt, incomplete, error, or idle. - Budgets, observability, and notifications: Pre-spawn ceilings on iterations, cost, duration, and idle streaks; status/watch pure-reader views; end-of-run macOS or webhook notifications; optional dashboard status frames. - Use Case: Point it at a development roadmap overnight with --adapter develop-next --max-duration 8h --max-cost 20 and it works items sequentially until the frontier empties, a halt occurs, or a budget cap is reached. ## Quick Start Ask the agent to run the loop-supervisor dry-run for the develop-next adapter to print the plan and exact claude argv before starting an unattended roadmap run.

Frequently Asked Questions about loop-supervisor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run an unattended Claude loop overnight?▼

Launch run-loop.mjs from a terminal with the run subcommand, for example with --adapter develop-next --max-duration 8h --max-cost 20. It spawns one fresh claude -p per iteration and stops on an empty frontier, a halt, or a budget cap.

What is the difference between loop-supervisor and the built-in /loop?▼

The built-in /loop re-invokes the same conversation each iteration, so context accumulates and quality degrades silently. loop-supervisor spawns a new claude -p process per iteration with empty context and classifies outcomes from files on disk.

How does the loop detect whether an iteration made progress?▼

A pure classifier checks filesystem post-conditions: run-state files, the pipeline lock, halt-file timestamps, and a git progress oracle comparing commit SHAs on the base branch. It never reads the assistant's prose.

Why does the supervisor fail to resolve node or claude on PATH?▼

In non-interactive shells node may be an nvm shell function rather than a binary, so the supervisor resolves both binaries to absolute paths before starting. Run dry-run first to see what it resolved, or launch from a login shell.

Can I monitor a running loop from another terminal?▼

Yes, the status and watch subcommands are pure readers that take no lock and spawn nothing, so they are safe over SSH, concurrently, and mid-iteration. status --json emits a machine-readable snapshot.

What are the limitations of the loop-supervisor?▼

It is sequential only; two supervisors in one working tree collide on the pipeline lock. Each iteration also re-primes CLAUDE.md and skill files, so there is a real per-iteration cost floor even with prompt caching.