ralph-wiggum-plugin

ralph-wiggum-plugin

A CLI-agnostic Ralph autonomous-development loop. Drives either the Claude Code (claude) or Cursor (cursor-agent) headless CLI from a terminal, with token accounting, context rotation, gate-run verification, guard hooks, retry/backoff, and Spec Kit integration.

"That's the beauty of Ralph — the technique is deterministically bad in an undeterministic world." — Geoffrey Huntley

What it is

The Ralph loop is a shell script you run in a terminal. It spawns the agent CLI as a subprocess, reads its stream-json output, tracks tokens, rotates context when the window fills, and keeps going until the task is done or the safety cap on agent respawns is reached. The loop is editor-agnostic: the editor you have open is irrelevant.

A healthy ralph loop runs as one continuous agent process — it commits as it goes and keeps moving until a real stop condition fires. It only respawns the agent (looping) on hard signals: context-window pressure, consecutive gate failures, or a rate-limit backoff. Looping is fine when needed but flow is much better — a single small spec usually completes in one loop.

The Claude Code plugin wrapping (slash commands, plugin manifest, and specialist skills) is a Claude Code-only enrichment. For Claude Code users, install as a plugin — it unlocks the acceptance-evaluation skills (running-acceptance-evaluation, verifying-acceptance-criteria, addressing-acceptance-gaps) and the guard hook that enforces gate discipline. Standalone-script users still get the full loop infrastructure but without those extras.

Feature set

The plugin's intended behaviors, with where each is implemented. Use this as the inventory when reviewing the loop's reliability end-to-end.

Graceful context management & restarts

• Stream parser fires WARN at 87.5% of the token threshold (stream-parser.sh:emit_warn_or_rotate) and touches .ralph/context-warning-active.
• The framing prompt instructs the agent to check context-warning-active and stop-requested after every commit and yield with a handoff write if either is present.
• Loop detects 🤝 GRACEFUL YIELD when handoff.md was written this iteration (_detect_graceful_yield in ralph-common.sh) — distinguishes a good yield from a force-killed ROTATE / TURN_END.
• At 100% (ROTATE_THRESHOLD), the loop force-kills the agent. The next session reads the inlined handoff block from build_prompt.

Stop-signal adherence

• Touch .ralph/stop-requested to ask the loop to halt. Agent honors at the next post-commit breadcrumb check.
• The loop's driver-side check (run_ralph_loop) honors stop-requested if the agent didn't yield voluntarily — distinguishing graceful from forced via the same _detect_graceful_yield helper.
• stop-requested honored → loop writes .ralph/.loop-stopped-by-user → --evaluate chain is skipped (operator intent is "halt", not "ready for verification").

Script call filters & transparent rewrites

• PreToolUse hook (ralph-guard.sh) registered via hooks/hooks.json (record-keyed-by-event-name schema; the wrong-schema 0.12.4 bug is fixed in 0.12.5).
• .ralph/command-policy has five sections, evaluated in order: [gates] → [rewrite] → [deny] → [wrap] → [protect].
  • [gates] — required. Declares the three tier-gate commands (basic | <cmd>, full | <cmd>, final | <cmd>). Loop refuses to start if any are missing.
  • [rewrite] — project-specific regex transforms (e.g. pnpm nx X → pnpm X). Transparent via updatedInput.
  • [deny] — hard block with permissionDecision: deny (e.g. containerized E2E).
  • [wrap] — auto-routes other commands through gate-run.sh <label> <cmd> transparently. Labels: basic | full | final | unit | integration | e2e | lint | format.
  • [protect] — bare invocation OK; pipe/redirect denied.
• Canonicalization (_canonicalize in ralph-guard.sh): env-prefix stripped, pipes/redirects stripped, pnpm run X / pnpm exec X normalized to pnpm X. Compound chains (pnpm A && pnpm B) split — if any segment matches [wrap], the whole chain is rewrapped on just that segment.
• Activity-log emoji: 🔀 GUARD REWRITE on transparent rewrites, ⛔ GUARD DENY on hard blocks.

Multi-consecutive gate checks without interleaving writes/edits

• ralph-guard.sh's gate-without-write check blocks re-running a gate when no Write/Edit happened since the last gate (LAST_WRITE_TS vs LAST_GATE_TS in $XDG_STATE_HOME/ralph/<workspace-hash>/).
• Prevents the "run gate → read output → re-run gate for more output" anti-pattern that wastes minutes per loop.