Auto loop
Drive a Claude Code session toward a verifiable goal until done or a hard cap fires - autonomous loop, no user intervention. Use for refactor batches, test-coverage runs, migration loops where success is a check command (tests, lint, custom predicate) plus a fresh-context audit. Hosts the loop intra-session via Stop hook with two-vote completion gate; supports optional Codex /goal delegation.From its SKILL.md
npx -y skills add vanducng/skills --skill auto-loopAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
5.4 KB, ~1.3k tokens by cl100k_base, as published. Nobody here has run it
auto-loop
What this skill is - and isn't
| Skill | Question it answers | Output |
|---|---|---|
/loop | "Re-run this prompt every N minutes." | Cron-style recurrence |
/ralph-loop | "Bash-while loop external to Claude." | Subprocess churn |
vd:cook | "Execute the plan, phase-by-phase, with review gates." | Phased delivery |
vd:optimize-loop | "Improve a measurable metric over N bounded iterations." | Best metric value (auto keep/discard) |
vd:auto-loop | "Drive toward this goal until verified done or a cap fires - no babysitting." | Verified completion or graceful drain |
Auto-loop pursues. It does not design (use vd:brainstorm/vd:plan first) and it does not poll on a clock (use /loop). The exit condition is a two-vote completion gate: a user-supplied verifier command and a fresh-context audit subagent both vote achieved.
Modes
| Flag | Behaviour |
|---|---|
| (default) | Run intra-session loop hosted by Stop hook until two-vote gate or hard cap. |
--codex | Delegate to native Codex /goal (requires codex ≥ 0.128.0 + ChatGPT auth). |
--status | Read-only snapshot of current loop state. Exits with status-coded code. |
--cancel | Tear down Stop hook, mark state cancelled, leave working tree intact. |
Hard rules
- Two-vote completion gate.
status: achievedis not terminal until verifier passes 2× and audit subagent votesachieved. False positives loop back asunmet. - Hard caps non-negotiable. Iterations / tokens / wallclock - at least one always set. Wallclock cap defaults to
4hand is the floor cap (always present even if user sets only iter or token caps). - State file is source of truth.
.auto-loop/goal-state.jsonround-trips across compaction and restart. Schema-validated atomic writes only. - No
--dangerously-skip-permissions. Default sandbox = workspace-write semantics. Loops needing broader access must allow-list explicit globs ingoal.mdscope. - No audit recursion.
VD_AUTOLOOP_DEPTHenv-flag gate; audit subagents may not invokevd:auto-loop,ralph-loop, orcodex /goal. - No
ScheduleWakeupfor loop primitive. Stop-hook re-feed is the loop; ScheduleWakeup is reserved for/loopand has known re-fire bugs (anthropics/claude-code#51304, #54086).
Arguments
| Flag | Default | Notes |
|---|---|---|
<goal> (positional) | - | Required for default mode. Use goal.md shape if multi-line. |
--verify <cmd> | - | Required for default mode. Shell command; exit 0 = pass. Run twice per gate check. |
--goal-file <path> | goal.md | Markdown spec (overrides positional <goal>). See references/goal-spec-format.md. |
--max-iterations <N> | 40 | Hard ceiling; budget-limited reason iterations. |
--max-tokens <T> | 2000000 | Advisory unless ccusage present; falls back silently if probe noisy. |
--max-wallclock <D> | 4h | Floor cap - always enforced. Accepts 30m, 2h, 4h30m. |
--restart-pct <N> | 70 | Context % triggering phase-restart compaction. |
--codex | off | Delegate to Codex /goal. |
--status | - | Read-only inspect. |
--cancel | - | Stop active loop. |
--status / --cancel / --codex are mutually exclusive with each other and with default-mode args.
Workflow position
vd:plan (decide what) → vd:auto-loop (drive to done) → vd:journal (record what happened).
Use vd:auto-loop when (a) the goal has a single-shot verifier and (b) you'd otherwise babysit vd:cook for hours. Use vd:cook instead when phases want human review between them.
Anti-patterns
- "Tests pass = done." No - tests passing is one vote. The audit subagent independently re-reads goal vs diff.
- "Disable wallclock cap to let it run all night." No - wallclock is the floor. Raise it (
--max-wallclock 12h) instead. - "Run two
vd:auto-loopsessions in the same workspace." Refused - heartbeat lock prevents it. - "Use ScheduleWakeup with
vd:auto-loopas the prompt." Re-fire bug. Use the in-process Stop-hook host. - "Audit subagent calls another
vd:auto-loopfor sub-goals." Recursion guard refuses; promote to peer skill instead.
Argument parser
scripts/dispatch.sh parses the flags listed above, validates mutual exclusion,
seeds .auto-loop/heartbeat.json + goal-state.json, and installs the Stop
hook. Invoke with no arguments to print references/usage.md.
See also
references/usage.md- bare-invocation help text.references/goal-spec-format.md-goal.mdschema (phase 2).references/architecture.md- state machine + contract diagram (phase 8).references/smoke-test.md- reproducible end-to-end recipe (phase 8).references/codex-delegation.md- when and how--codexworks (phase 7).references/troubleshooting.md- common failure modes (phase 8).
What ships with it: 39 files
97.4 KB alongside SKILL.md, 19 of them executable
references/
- architecture.md6.7 KB
- codex-delegation.md3.2 KB
- goal-spec-format.md2.3 KB
- smoke-test.md2.1 KB
- troubleshooting.md4.3 KB
- usage.md3.3 KB
scripts/
- cancel-loop.shruns2.1 KB
- check-budget-caps.shruns3.3 KB
- check-completion-gate.shruns2.9 KB
- delegate-to-codex.shruns2.1 KB
- dispatch.shruns5.4 KB
- drift-watchdog.shruns2.8 KB
- .gitkeep0 B
- install-stop-hook.shruns1.5 KB
- parse-goal-spec.shruns3.6 KB
- probe-context-pct.shruns1.6 KB
- probe-token-usage.shruns1.2 KB
- restart-fresh-session.shruns2.0 KB
- run-verifier.shruns1.1 KB
- spawn-audit-subagent.shruns4.1 KB
- _state-dir.shruns723 B
- state-rw.shruns4.1 KB
- status-reader.shruns2.8 KB
- stop-hook-handler.shruns9.9 KB
- uninstall-stop-hook.shruns1.0 KB
- write-compaction-summary.shruns2.4 KB
templates/
tests/
- test-budget-caps.bats2.1 KB
- test-cancel-status.bats2.0 KB
- test-completion-gate.bats2.0 KB
- test-parse-goal-spec.bats1.3 KB
- test-state-rw.bats2.2 KB
- test-stop-hook-handler.bats3.4 KB
- state-schema.json2.7 KB
Gives 0 of the 12 instructions most quality gates skills give in ~1.3k tokens
Counted across 1,524 of the 2,830 authors here whose files we hold, read 2026-09-06
- Read full output and check exit codein 45 of 1524, across 40 files
- Verify output confirms the claimin 44 of 1524, across 39 files
- Identify the command that proves the claimin 43 of 1524, across 39 files
- Execute the full verification commandin 36 of 1524, across 30 files
- Produce a verification reportin 34 of 1524, across 18 files
- Review git diff changesin 30 of 1524, across 16 files
- Fix build failures immediatelyin 29 of 1524, across 9 files
- Group findings by severityin 28 of 1524
- State claim only with evidencein 27 of 1524, across 22 files
- Verify regression tests with red-green cyclein 26 of 1524, across 22 files
- Run the full test suitein 26 of 1524, across 25 files
- Run test suite with coveragein 25 of 1524, across 10 files
Said here and by no other author read
- use a two-vote completion gate
- set at least one hard cap
- use the stop hook for looping
- allow list explicit globs for broader access
- use goal file for multi-line goals
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.