ralph-loop

name

ralph-loop

description

Scaffolds and runs a Ralph Wiggum loop — Geoff Huntley's "stupid simple while-loop" pattern for autonomous overnight coding sessions. Authors PROMPT.md + fix_plan.md + ralph.sh, gates them through a plan review, then runs `while: cat PROMPT.md | claude -p` in a fresh context window per iteration (defeats compaction + context-rot). Useful for long worklists with clear acceptance criteria (test suite passes, fix_plan items checked off), reverse-engineering, spec-driven refactors, "fix all the failing crons overnight" sweeps. Composes with `/cortex-goal` — Ralph is the third option alongside native `/loop` (interval-based) + `/goal` (haiku-verifier). Inherits cortex-x R1+R2 discipline, cost ceilings, and the operator killswitch file. Triggers (EN+CZ) "/ralph-loop", "/ralph", "ralph wiggum", "run ralph", "spusť ralph", "loop until done", "loop dokud nebude hotovo", "overnight loop", "autonomous overnight", "fix all X until tests pass", "oprav všechny X dokud projdou testy", "vibe-clone".

/ralph-loop — Ralph Wiggum autonomous loop scaffolder + runner

Status: v0-experimental (2026-05-25). The R2 security review flagged this skill as carrying the canonical lethal-trifecta blueprint when run with --dangerously-skip-permissions. Do not run on production code or any repo where you cannot git reset --hard to recover. See § Known risks v0 at the bottom of this document. Hardened path forward in references/cost-discipline.md § Roadmap.

Voice charter: see standards/voice.md. No greetings, no emoji, counts-not-praise. When invoked you are scaffolding a real shell loop that will spend real money — observe + tune, not perform.

Grounded in Geoff Huntley's June 2025 pattern (ghuntley.com/ralph/) and the HumanLayer post-mortems. Key insight: a one-line shell loop with a fresh context window per iteration outperforms multi-agent orchestration on convergent worklists because it defeats compaction and context-rot. The skill is mostly discipline, not code — the loop itself is 3 lines of bash.

When to invoke

• /ralph-loop or /ralph explicit invocation
• "loop until done" / "loop dokud nebude hotovo"
• "overnight" / "autonomous overnight" / "weekend run" / "běhej v noci"
• "fix all X until tests pass" / "oprav všechny X" / "ship them all"
• "vibe-clone" / "reverse-engineer X into specs"
• After an audit produces a long fix_plan and the operator wants it done overnight

Don't invoke for:

• Single-shot tasks (use direct chat — overhead not worth it)
• Tasks without an automated verifier (no npm test / no acceptance criterion → loop drifts forever)
• High-stakes prod code with no rollback (DB migrations, payment flows, anything irreversible)
• Ambiguous specs ("make it better" — garbage in → infinite iteration)
• Codebases the loop user can't git reset --hard (no recovery path)

How Ralph differs from /loop and /goal

	When to use	Context window	Termination
/loop (Claude Code native)	Recurring poll on interval ("check deploy every 5 min")	Reuses session context across iterations	Operator stops
/goal (Claude Code native)	Long focused session 14h–5d on one acceptance frontier	Single context with haiku verifier	Verifier emits COMPLETE
/ralph-loop (this skill)	Convergent worklist, fresh context per iteration	Brand new context every loop	fix_plan.md empty OR completion-promise OR max-iterations OR circuit breakers

Ralph's unique value = the fresh context window per iteration. /loop and /goal reuse session context, so they rot on long worklists. Ralph re-injects the same artifacts (PROMPT.md + fix_plan.md + specs/) into a blank window each loop — every iteration starts fresh.

Phase 0 — Pre-flight refuse-conditions

Before scaffolding any artifacts, check all 6 conditions. If any fails, refuse with a specific reason — don't bargain.

Condition	Check	Fix if fails
Git tree clean	git status --porcelain empty	Commit/stash work first
Branch is not main	git branch --show-current ≠ main (Ralph commits per iteration)	git switch -c ralph/<usecase>
Test harness exists	npm test / pytest / equivalent succeeds today	No test = no termination signal; refuse
STEWARD_HALT killswitch absent	~/.cortex/STEWARD_HALT doesn't exist	Operator chose to halt all spend — respect it
Daily cost cap headroom	Estimated cost (iterations × avg-tokens × model-price) ≤ remaining STEWARD_DAILY_USD_CAP	Lower iteration cap or wait until reset
Recovery point	The last commit must be a known-good baseline so git reset --hard HEAD~N is meaningful	Commit a baseline before scaffolding

Surface a 6-row table back to the operator with each check pass/fail and the fix.

Phase 1 — Author the three artifacts

Ralph runs on three files. The skill writes all three into cortex/ralph/<usecase-slug>/ (gitignored — these are scratch).

1.1 — PROMPT.md (the loop body)

What the prompt does each iteration:

1. Loads fix_plan.md
2. Loads specs/ (if any)
3. Picks the highest-priority unchecked item
4. Searches the codebase (verbatim guardrail from Huntley: "Before making changes search codebase, don't assume not implemented")
5. Implements it (verbatim guardrail: "DO NOT IMPLEMENT PLACEHOLDER OR SIMPLE IMPLEMENTATIONS. WE WANT FULL IMPLEMENTATIONS")
6. Runs tests
7. If green → commits + checks the item off in fix_plan.md + emits completion signal
8. If red → leaves a note in fix_plan.md (> blocker: X — retry next loop) and stops the iteration

The skill generates PROMPT.md from templates/PROMPT.template.md by substituting {{USECASE}}, {{SUCCESS_CRITERIA}}, {{NON_GOALS}}, {{COST_CEILING}}.

1.2 — fix_plan.md (the worklist)

Markdown checklist, one item per task. Each item has:

• - [ ] [priority] short title
• 2-3 lines of context (file paths, expected behavior, acceptance test)
• Optional: link to specs/<item>.md for long-form spec

The skill generates fix_plan.md skeleton from templates/fix_plan.template.md. Operator fills in the list before the loop starts.

1.3 — ralph.sh (the loop wrapper)

The actual shell loop. Generated from templates/ralph.template.sh (bash) and templates/ralph.template.ps1 (PowerShell). The loop:

• Caps iterations (MAX_ITERATIONS=50 default)
• Caps wall-clock (MAX_HOURS=8 default)
• Caps per-hour token spend (MAX_TOKENS_PER_HOUR=200000 default)
• Checks termination after each iteration (fix_plan empty / completion-promise / circuit breaker)
• Writes journal lines to cortex/ralph/<usecase>/journal.jsonl
• Reads ~/.cortex/STEWARD_HALT between iterations (operator killswitch)

Phase 1.5 — Plan gate (operator approval)

After Phase 1 generates all three artifacts, pause and show the operator:

1. The pre-flight table (Phase 0)
2. fix_plan.md content (so they can edit it)
3. PROMPT.md content (so they spot drift triggers)
4. Estimated cost ceiling at full iteration cap
5. Termination conditions for this run
6. Recovery instruction (git reset --hard <baseline-sha> + path to scratch dir)

Operator approves with y / adjusts / cancels. Never start the loop without this gate — the loop spends money and modifies the repo.

Phase 2 — Run mode selection

Mode	When to use	Behavior
--planner-only	Spec hasn't been written yet	Loop only edits fix_plan.md + specs/ — never touches source code. Used to converge on a worklist before opening implementation. Huntley's canonical "plan" mode.
--builder-only (default)	fix_plan + specs already exist	Loop only implements items from fix_plan, runs tests, commits, checks off. Never adds new items.
--planner-then-builder	Long unstructured ask	First N iterations are planner mode (write fix_plan + specs); then auto-switch to builder mode when fix_plan reaches target_item_count
--single-pass	Just one iteration as a smoke test	Run the loop body once, exit. Cheapest validation that the prompt + artifacts work. Use BEFORE long runs.

Default to --single-pass first, then --builder-only. Never start with unbounded builder mode without a single-pass dry run.

Phase 3 — Spawn the loop

Isolate first. Before any execution surface, create a throwaway worktree so a corrupted tree never touches the primary checkout: git worktree add ../ralph-<usecase> ralph/<usecase> (or claude --worktree <usecase>), then run ralph.sh from there. The Known-risks § lethal-trifecta mitigation depends on this. Skip only for --single-pass smoke tests.

Three execution surfaces:

• Foreground bash — ./cortex/ralph/<usecase>/ralph.sh directly. Use for short runs (< 1h), to watch live, to abort fast.
• tmux pane — tmux new-session -d -s ralph-<usecase> 'cd cortex/ralph/<usecase> && ./ralph.sh'. Use for unattended overnight. Operator attaches with tmux a -t ralph-<usecase> and detaches with Ctrl+B → D.
• run_in_background Bash tool — when invoked from this session, spawn the loop in the background and monitor via journal.jsonl tail. Use sparingly — operator should drive long runs themselves.

For unattended runs, default to tmux + stream-json output (claude -p --output-format stream-json). The journal.jsonl is appended per iteration with: {iteration, started_at, ended_at, items_checked_off, cost_usd, exit_reason}.

Native monitoring alternative: instead of tailing journal.jsonl by hand, Claude Code's Monitor tool (v2.1.98+) can watch the journal + interject on exit_reason / cost-spike events without you polling — ask Claude to Monitor cortex/ralph/<usecase>/journal.jsonl and flag any exit_reason or iter_cost > $5. Pair with PushNotification for an "overnight run done" phone alert.

Phase 4 — Monitor + tune ("sit on the loop, not in it")

Huntley's verbatim guidance: "Sit on the loop, observe + tune like a guitar — don't sit in it."

The skill exposes 3 monitoring contracts:

• cortex/ralph/<usecase>/journal.jsonl — append-only per-iteration record
• cortex/ralph/<usecase>/STATUS — symlink to current iteration's stdout (overwritten each loop)
• cortex/ralph/<usecase>/COST — running cost total

When the operator says "how's ralph doing" mid-run, read all three + report: iteration count / items closed / items added / current spend / time elapsed / estimated time to fix_plan empty.

Tuning during the run = editing PROMPT.md between iterations (the next loop picks up the new prompt). Don't edit fix_plan.md while a loop is running — race condition with the model's own check-off writes.

Phase 5 — Termination conditions

The loop stops when any one of these fires (in priority order):

1. fix_plan.md has zero unchecked - [ ] items — primary success exit
2. ~/.cortex/STEWARD_HALT exists — operator killswitch, immediate exit
3. Iteration cap reached (MAX_ITERATIONS, default 50)
4. Wall-clock cap reached (MAX_HOURS, default 8)
5. Cost cap reached (MAX_COST_USD, default $20 for the whole run, separate from daily Steward cap)
6. Completion promise — if PROMPT.md declares one, the loop matches <promise>COMPLETE</promise> in stdout and exits
7. Circuit breakers:
   • 3+ consecutive iterations without items checked off → NO_PROGRESS
   • 5+ identical errors in journal.jsonl → STUCK_ERROR
   • 2+ consecutive git reset --hard events → CORRUPTION

Each exit reason logs a final line to journal.jsonl and writes a one-screen summary to cortex/ralph/<usecase>/REPORT.md.

Full termination semantics + 6 circuit breakers + opt-in completion-promise format → references/termination.md.

Phase 6 — Post-loop verification

After the loop exits (for any reason), run a final sweep:

1. git status — confirm tree is clean (loop commits per iteration, so it should be)
2. npm test — full suite, not just the last iteration's slice
3. R2 review pipeline — spawn acceptance-auditor + blind-hunter + ssot-enforcer + edge-case-hunter against the full diff (loop commits aggregate into one PR-sized change)
4. Cost reconciliation — sum journal.jsonl cost_usd, compare to OpenRouter dashboard
5. Recommendations file — surface any items the loop added to fix_plan but didn't close (debt for next run)

Then write REPORT.md (paste-ready PR description) and surface it. Operator decides: merge / iterate again / abandon + git reset --hard <baseline>.

Anti-patterns the skill refuses to scaffold

• fix_plan.md item with no acceptance test → reject, force operator to add a verifier
• PROMPT.md asking for "improvement" / "refactoring" without target → reject, ambiguous
• MAX_ITERATIONS unset or > 200 → reject, cost cap discipline
• Running on main branch → reject, force ralph/<usecase> branch
• Running with dirty tree → reject
• Running without baseline commit → reject (no recovery path)
• Running when STEWARD_HALT exists → respect the killswitch

Cost discipline

Defaults that the skill enforces unless operator explicitly overrides:

• MAX_ITERATIONS=50
• MAX_HOURS=8 (one overnight window)
• MAX_COST_USD=20 per run
• MAX_TOKENS_PER_HOUR=200000
• Model: claude-sonnet-4-6 (Ralph baseline; switch to opus only when sonnet stalls)

The benchmark from HumanLayer: "Sonnet 4.5 on a bash loop, known as Ralph, costs ~$10.42/hour." Sonnet 4.6 is similar. Budget realistically: 8h overnight = ~$80 spend ceiling on the upper bound.

Full cost-discipline framework + per-iteration spend caps + circuit breakers → references/cost-discipline.md.

Variants

Ralph isn't one pattern — it's three. Full anatomy + verbatim prompt templates for each → references/patterns.md:

• Planner / Builder split (Huntley canonical) — two prompt files, planner-only first run, then builder
• Verifier loop (Anthropic plugin) — Stop hook intercepts exit, re-feeds prompt until <promise>COMPLETE</promise>
• Spec-driven Ralph — @specs/stdlib/* re-injected each loop, used to reverse-engineer codebases into specs
• AFK Ralph — streaming JSON variant for unattended runs
• TDD Ralph — failing test is the next iteration's signal, items close when test goes green
• Subagent fanout Ralph — Huntley's verbatim rule: "500 sonnet subagents for reads, 1 sonnet for writes"

Companion references

The main SKILL.md keeps the runtime contract. Deep guidance lives in companion files:

• templates/PROMPT.template.md — paste-ready PROMPT.md skeleton with substitution slots + Huntley's verbatim guardrails
• templates/fix_plan.template.md — fix_plan.md skeleton + 1 worked example
• templates/ralph.template.sh — bash loop wrapper with caps + termination + journal
• templates/ralph.template.ps1 — PowerShell variant for Windows
• references/patterns.md — 6 Ralph variants with verbatim prompts + when each wins
• references/termination.md — 7 exit conditions + 6 circuit breakers + completion-promise syntax
• references/cost-discipline.md — budgets, per-iteration caps, OpenRouter cost tracking, daily/weekly/monthly reconciliation

Output discipline (matches voice.md)

• No greetings before scaffolding ("Tady je váš Ralph loop!" — banned)
• No emoji in operator-facing text
• Counts not praise: "Generated PROMPT.md + fix_plan.md + ralph.sh into cortex/ralph/cron-stability/. 7 items in fix_plan, estimated cost $14 at MAX_ITERATIONS=50." not "Krásný plán!"
• When unsure of a fix_plan item, ask one tight question instead of guessing
• Cite [cortex/recall] + footnote when recalling prior Ralph runs from cortex/ralph/*/REPORT.md

Slot validation (substitution safety)

When the skill writes ralph.sh / ralph.ps1 it substitutes operator-provided values into shell heredocs and double-quoted strings. Unsanitized values are a command-injection vector. Before substitution the skill MUST validate every slot against an allowlist regex:

Slot	Regex	Example accept	Example reject
{{USECASE_SLUG}}	^[a-z0-9-]{1,40}$	cron-stability	cron"; rm -rf ~
{{USECASE}} (display)	^[A-Za-z0-9 _\-./]{1,80}$	Cron stability sweep	embedded backticks / $() / shell metas
{{BRANCH}}	^[a-zA-Z0-9._/-]{1,80}$	ralph/cron-stability	main; git push
{{BASELINE_SHA}}	^[0-9a-f]{7,40}$	abc1234	--upload-pack=…
{{TIMESTAMP}}	^[0-9TZ:.-]{1,30}$	ISO-8601 string	shell metas

Reject on first violation. The scaffolder refuses to write the loop until the operator picks valid values.

Known risks v0

The R2 security review (2026-05-25) returned CANNOT SHIP AS-IS for production environments. The skill ships as v0-experimental with these caveats documented:

Architectural risks (require operator awareness)

1. Lethal trifecta in one process — Ralph reads private repo data + ingests untrusted fix_plan.md + has external network egress (model can curl / git push). --dangerously-skip-permissions disables Claude Code's in-band defense (including the block-destructive hook). Mitigation v0: run only on repos you can git reset --hard; use a fresh ralph/<usecase> branch; never run on prod credentials. Native FS isolation (available now): Claude Code exposes EnterWorktree / claude --worktree <name> + an isolation: "worktree" option on the Agent tool — run Ralph inside a throwaway worktree so a corrupted tree never touches your primary checkout (auto-cleaned if no changes land, otherwise the branch + path are returned). Prefer this over running in-place. Roadmap v1: ralph.sh auto-creates the worktree; document the container/devcontainer execution path.
2. Cost cap is model-self-reported — total_cost_usd is extracted from the model's own stream-json output. A prompt-injected fix_plan.md could ask the model to falsify the field, bypassing MAX_COST_USD. Mitigation v0: MAX_ITERATIONS cap is hard-enforced by the shell — that's your real budget ceiling. Roadmap v1: out-of-band billing-API cost gate between iterations.
3. block-destructive hook disabled — when running with --dangerously-skip-permissions, the cortex-x block-destructive hook does NOT intercept rm -rf, git push --force, git reset --hard, DROP TABLE, etc. Mitigation v0: set RALPH_REQUIRE_HOOKS=1 to run without the dangerous flag (slower, prompts on each tool call, but defense-in-depth intact). Roadmap v1: ship a Ralph-aware permission allowlist that pre-approves the safe tool subset (Read/Grep/Glob/Edit/npm test) while leaving destructive ones gated.

Implementation risks (operator monitoring)

4. Branch protection not auto-verified — Phase 0 refuses main/master, but doesn't probe GitHub branch-protection rules. If the repo has no branch protection, the model can still git push origin main --force via tool use. Mitigation v0: enable branch protection on the target remote before running. Roadmap v1: gh api repos/:owner/:repo/branches/main/protection pre-flight check.
5. PROMPT.md / journal.jsonl persist on disk — cortex/ralph/ is gitignored but stays on disk forever. If you include secrets in the usecase description, they land in 50+ iteration logs. Mitigation v0: never paste credentials into usecase / fix_plan content; pre-flight scans PROMPT.md for sk-, ghp_, xox[bp]-, AKIA, -----BEGIN and refuses. Roadmap v1: auto-purge logs > 30 days; chmod 700 on the scratch dir.
6. Pre-commit hooks requiring TTY — if the repo has husky / lefthook / pre-commit hooks that prompt interactively, --dangerously-skip-permissions doesn't help (non-interactive bash blocks). The loop will close 0 items, trip NO_PROGRESS after 3 iter and exit. Mitigation v0: disable interactive hooks for the run, or set HUSKY=0 / equivalent in the env. Roadmap v1: Phase 0 hook probe.

Acceptance for v0 use

Ralph v0 is safe to run when all apply:

• Personal repo or test fixture, never production
• Running inside a dedicated git worktree (git worktree add / claude --worktree) — corruption stays off your primary checkout
• ralph/<usecase> branch (never main/master)
• Clean tree at baseline + you remember the baseline SHA
• You can git reset --hard <baseline> to recover
• No secrets in PROMPT.md or fix_plan items
• Branch protection enabled on origin/main
• MAX_ITERATIONS=20 for first run (caps blast radius)
• You check on it every 30 min ("sit on the loop, not in it") — or wire the Monitor tool + PushNotification so it reaches you instead

If any of those don't hold, defer Ralph and use /cortex-goal (which runs in your foreground session under normal Claude Code permissions) instead.

Sources

Research May 2026:

• ghuntley.com/ralph/ — canonical post (Jul 2025)
• ghuntley.com/loop/ — "everything is a ralph loop"
• github.com/ghuntley/how-to-ralph-wiggum — reference repo
• humanlayer.dev/blog/brief-history-of-ralph — production reports
• github.com/anthropics/claude-code plugins/ralph-wiggum — official plugin (Dec 2025)
• github.com/frankbria/ralph-claude-code — circuit-breaker variant
• HumanLayer: 6 repos shipped overnight, 6-hour autonomous frontend refactor
• Cost benchmark: Sonnet 4.5/4.6 on bash loop ~$10.42/hour

R2 review reports (2026-05-25): acceptance-auditor (approved-conditional), blind-hunter (8 P0, 12 P1), edge-case-hunter (5 P0, 6 P1), security-auditor (CANNOT SHIP AS-IS, 4 CRIT + 5 HIGH). The CRIT findings drove the v0-experimental label + Known risks section above.