The Ralph Wiggum plugin implements an iterative self-referential development loop within a Claude Code session. When activated, the plugin intercepts session termination and feeds the same initial prompt back to Claude, allowing it to see its previous work and continuously iterate on the task until completion criteria are met.
This plugin is designed for tasks requiring iterative refinement, self-correction, and progressive improvement where the agent benefits from seeing its accumulated work across multiple attempts.
For information about other development workflow plugins, see Development Workflow Plugins. For details on the hook system that enables this plugin's behavior, see Hook System.
The Ralph Wiggum plugin operates by installing a session stop hook that prevents normal exit and re-injects the original prompt. The plugin maintains state in a local markdown file that tracks iteration count, completion criteria, and the prompt text.
Sources: plugins/ralph-wiggum/commands/ralph-loop.md1-19 plugins/ralph-wiggum/scripts/setup-ralph-loop.sh1-204
The plugin uses .claude/ralph-loop.local.md as its state file, combining YAML frontmatter with the original prompt text:
Sources: plugins/ralph-wiggum/scripts/setup-ralph-loop.sh140-150
/ralph-loop CommandThe primary command initializes a Ralph loop in the current session.
Syntax:
/ralph-loop [PROMPT...] [OPTIONS]
Arguments:
PROMPT... - Initial prompt text (multi-word without quotes)Options:
| Option | Type | Default | Description |
|---|---|---|---|
--max-iterations <n> | integer | 0 (unlimited) | Maximum iterations before auto-stop |
--completion-promise '<text>' | string | null | Promise phrase for completion detection |
-h, --help | flag | - | Display help message |
Examples:
Implementation Details:
The command executes plugins/ralph-wiggum/scripts/setup-ralph-loop.sh via Bash tool, which:
.claude directory if needed setup-ralph-loop.sh131Sources: plugins/ralph-wiggum/commands/ralph-loop.md1-19 plugins/ralph-wiggum/scripts/setup-ralph-loop.sh1-204
/cancel-ralph CommandTerminates an active Ralph loop by removing the state file.
Syntax:
/cancel-ralph
Execution Flow:
Sources: plugins/ralph-wiggum/commands/cancel-ralph.md1-19
The Ralph loop supports two mechanisms for automatic termination.
When --max-iterations N is specified, the stop hook checks iteration >= max_iterations before re-injecting the prompt. If true, the session is allowed to exit normally.
Configuration:
--max-iterations flag setup-ralph-loop.sh61-86max_iterations frontmatter field setup-ralph-loop.sh1440 means unlimited iterations setup-ralph-loop.sh68When --completion-promise 'TEXT' is specified, the stop hook scans Claude's output for the exact phrase wrapped in <promise> XML tags.
Requirements:
<promise>TEXT</promise> exactly setup-ralph-loop.sh186Validation:
Critical Rule: The command documentation explicitly prohibits false completion promises ralph-loop.md18 setup-ralph-loop.sh188-202 emphasizing that the loop is designed to continue until genuine completion rather than allowing premature exit.
Sources: plugins/ralph-wiggum/commands/ralph-loop.md18 plugins/ralph-wiggum/scripts/setup-ralph-loop.sh87-103 setup-ralph-loop.sh179-203
The .claude/ralph-loop.local.md file uses YAML frontmatter combined with markdown content:
| Field | Type | Description |
|---|---|---|
active | boolean | Always true when loop is running |
iteration | integer | Current iteration number, starts at 1 |
max_iterations | integer | Maximum iterations, 0 for unlimited |
completion_promise | string | null | Promise text for completion, or null |
started_at | ISO8601 | UTC timestamp when loop was initiated |
View current iteration:
View full state:
Sources: plugins/ralph-wiggum/scripts/setup-ralph-loop.sh140-150 setup-ralph-loop.sh54-57
The Ralph Wiggum plugin operates through Claude Code's stop hook mechanism. When the state file exists, the stop hook:
.claude/ralph-loop.local.md to retrieve stateThe hook system is documented in Hook System. The Ralph plugin's stop hook is implicitly activated by the presence of the state file rather than explicit hook registration.
Sources: plugins/ralph-wiggum/commands/ralph-loop.md10-18
Ralph loops are effective for tasks requiring progressive refinement:
/ralph-loop Implement user authentication --max-iterations 15
The agent can:
Tasks where feedback accumulates in the repository:
/ralph-loop Optimize database queries --completion-promise 'All queries under 100ms'
The agent benchmarks, identifies slow queries, optimizes, and re-benchmarks until the promise becomes true.
Unlimited loops for open-ended tasks:
/ralph-loop Explore refactoring opportunities
Without iteration limits or completion promises, the loop continues indefinitely, requiring manual intervention via /cancel-ralph.
Warning: Unlimited loops (max_iterations: 0 and no completion_promise) will run forever and cannot be stopped manually except by cancellation setup-ralph-loop.sh166-167
Sources: plugins/ralph-wiggum/scripts/setup-ralph-loop.sh37-46
The plugin is distributed through the marketplace with the following configuration:
/ralph-loop, /cancel-ralphBash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*) ralph-loop.md4hide-from-slash-command-tool: true ralph-loop.md5 cancel-ralph.md4The commands are hidden from the general tool list because they modify session behavior in ways that should be explicitly invoked rather than automatically suggested.
For marketplace structure and plugin discovery, see Plugin Marketplace & Discovery.
Sources: plugins/ralph-wiggum/commands/ralph-loop.md1-6 plugins/ralph-wiggum/commands/cancel-ralph.md1-5
Refresh this wiki