Autonomous Loop
Understand Cavekit's stop-hook autonomous loop, budgets, and completion sentinel before running /ck:make or debugging sessions that will not stop.
Overview
Autonomous Loop is an agent skill most often used in Build (also Operate, Ship) that explains Cavekit's stop-hook state machine, budgets, and completion rules for long /ck:make runs.
Install
npx skills add https://github.com/juliusbrussee/cavekit --skill autonomous-loopWhat is this skill?
- Documents stop-hook.sh routing when .cavekit/loop is active
- Explains cavekit-tools.cjs routeDecision, status-block, and backprop-directive
- Covers completion sentinel, lock, per-task and session budgets, iteration cap
- Maps how /ck:make runs many agent iterations without manual nudges
- Clarifies user-approval gates inside an otherwise autonomous session
Adoption & trust: 4 installs on skills.sh; 1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You triggered /ck:make or a loop-backed command and cannot tell whether the session should continue, stop, or is stuck past budgets.
Who is it for?
Indie builders on Cavekit who run autonomous make flows or extend commands that must cooperate with the stop hook.
Skip if: Teams not using Cavekit, or builders who only need one-shot prompts with no /ck:make or loop commands.
When should I use this skill?
About to run /ck:make, debug a stuck session, or write a command that needs the loop; phrases like 'how does the loop work', 'stop hook', 'autonomous', 'completion sentinel', 'why is the session looping'.
What do I get? / Deliverables
You can predict hook routing, respect caps and approval gates, and debug looping behavior without guessing at Cavekit internals.
- Accurate mental model of loop routing
- Actionable debug steps for stuck autonomous sessions
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
The loop is authored and extended during Build when you wire commands; it is the canonical shelf because that is where you first must learn the machinery. Stop hooks, routeDecision, and iteration caps are agent-runtime tooling specific to Cavekit—not generic PM docs or ship-time security review.
Where it fits
Read loop architecture before adding a command that must inject the next prompt via routeDecision.
Trace stop-hook routing when a session never hits the completion sentinel.
Verify per-task and session budgets still gate autonomous runs before you ship a new /ck:make workflow.
How it compares
Framework internals for Cavekit's execution loop—not a substitute for brainstorming or writing implementation plans.
Common Questions / FAQ
Who is autonomous-loop for?
Solo developers using Cavekit with Claude Code who run /ck:make, write loop-aware commands, or troubleshoot sessions that keep injecting the next prompt.
When should I use autonomous-loop?
In Build before /ck:make or new loop commands; in Operate when debugging 'why is the session looping'; in Ship when validating autonomous runs stay within iteration and budget limits.
Is autonomous-loop safe to install?
It is explanatory documentation for local Cavekit behavior—check this page's Security Audits panel and review any hooks that run shell on your machine.
SKILL.md
READMESKILL.md - Autonomous Loop
# Autonomous Loop The loop lets a single `/ck:make` invocation run dozens of agent iterations without user intervention, while still respecting per-task budgets, session budgets, and explicit user-approval gates. ## Architecture ``` ┌─────────────────┐ Stop event ┌────────────────────┐ │ Claude Code │──────────────▶│ stop-hook.sh │ │ session │ │ (.cavekit/loop │ └─────────────────┘ │ active?) │ ▲ └─────────┬──────────┘ │ │ route() │ next prompt injected ▼ │ ┌────────────────────┐ │ │ cavekit-tools.cjs │ │ │ routeDecision() │ │ │ + status-block │ │ │ + backprop- │ │ │ directive │ │ └─────────┬──────────┘ │ │ └───────── {decision:"block", │ reason:<next prompt>} ◀─┘ ``` ## Files the loop touches All under `<project>/.cavekit/`: | File | Writer | Purpose | |---------------------------------|-----------------------|----------------------------------------------| | `.loop.json` | setup-loop | Sentinel; stop-hook no-ops without it. | | `.loop.lock` | stop-hook (heartbeat) | Single-writer lock. PID + hostname + ts. | | `state.md` | cavekit-tools | `phase`, `current_task`, `iteration`. | | `token-ledger.json` | token-monitor hook | Session + per-task token tallies. | | `task-status.json` | commands | Authoritative task registry. | | `.progress.json` | progress-tracker | Zero-context UI snapshot. | | `.auto-backprop-pending.json` | auto-backprop hook | Flag file from failed tests. | | `history/backprop-log.md` | backprop skill | Append-only trace log. | | `capabilities.json` | discover command | MCP + CLI tool detection. | ## Lifecycle 1. **Setup** — `/ck:make` calls: ``` node "${CLAUDE_PLUGIN_ROOT}/scripts/cavekit-tools.cjs" setup-loop ``` This writes `.loop.json` (activating the stop hook) and resets `state.md`. 2. **Work** — the agent does one wave of task execution per iteration. 3. **Stop fires** — Claude Code's Stop event triggers `stop-hook.sh`. The hook: - reads stdin for `session_id` and `transcript_path` - acquires / refreshes the lock - scans the last 20 transcript lines for `<promise>CAVEKIT COMPLETE</promise>` - if sentinel found → teardown + exit silently - else → asks `routeDecision()` for the next prompt - prepends the backprop directive if the flag file exists - returns `{"decision":"block","reason":<next prompt>}` 4. **Repeat** — Claude Code treats `decision:block` + `reason:...` as a new user message, so the session continues. 5. **Teardown** — one of: - completion sentinel detected - max-iterations reached (`CAVEKIT_MAX_ITERATIONS`) - session budget exhausted (`CAVEKIT_BUDGET_EXHAUSTED`) - lock stolen by another session (`CAVEKIT_LOCK_CONFLICT`) - user interrupt (hook returns no output; session st