surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / ralph-wiggum / scripts / setup-ralph-loop.sh

Anthony Morrisfix(ralph-wiggum): move multi-line bash from command to setup script (#16320) 5c92b97 · on Jan 5, 2026 History

203 lines · 6.8 KBRaw

1	#!/bin/bash
2
3	# Ralph Loop Setup Script
4	# Creates state file for in-session Ralph loop
5
6	set -euo pipefail
7
8	# Parse arguments
9	PROMPT_PARTS=()
10	MAX_ITERATIONS=0
11	COMPLETION_PROMISE="null"
12
13	# Parse options and positional arguments
14	while [[ $# -gt 0 ]]; do
15	case $1 in
16	-h\|--help)
17	cat << 'HELP_EOF'
18	Ralph Loop - Interactive self-referential development loop
19
20	USAGE:
21	/ralph-loop [PROMPT...] [OPTIONS]
22
23	ARGUMENTS:
24	PROMPT... Initial prompt to start the loop (can be multiple words without quotes)
25
26	OPTIONS:
27	--max-iterations <n> Maximum iterations before auto-stop (default: unlimited)
28	--completion-promise '<text>' Promise phrase (USE QUOTES for multi-word)
29	-h, --help Show this help message
30
31	DESCRIPTION:
32	Starts a Ralph Wiggum loop in your CURRENT session. The stop hook prevents
33	exit and feeds your output back as input until completion or iteration limit.
34
35	To signal completion, you must output: <promise>YOUR_PHRASE</promise>
36
37	Use this for:
38	- Interactive iteration where you want to see progress
39	- Tasks requiring self-correction and refinement
40	- Learning how Ralph works
41
42	EXAMPLES:
43	/ralph-loop Build a todo API --completion-promise 'DONE' --max-iterations 20
44	/ralph-loop --max-iterations 10 Fix the auth bug
45	/ralph-loop Refactor cache layer (runs forever)
46	/ralph-loop --completion-promise 'TASK COMPLETE' Create a REST API
47
48	STOPPING:
49	Only by reaching --max-iterations or detecting --completion-promise
50	No manual stop - Ralph runs infinitely by default!
51
52	MONITORING:
53	# View current iteration:
54	grep '^iteration:' .claude/ralph-loop.local.md
55
56	# View full state:
57	head -10 .claude/ralph-loop.local.md
58	HELP_EOF
59	exit 0
60	;;
61	--max-iterations)
62	if [[ -z "${2:-}" ]]; then
63	echo "❌ Error: --max-iterations requires a number argument" >&2
64	echo "" >&2
65	echo " Valid examples:" >&2
66	echo " --max-iterations 10" >&2
67	echo " --max-iterations 50" >&2
68	echo " --max-iterations 0 (unlimited)" >&2
69	echo "" >&2
70	echo " You provided: --max-iterations (with no number)" >&2
71	exit 1
72	fi
73	if ! [[ "$2" =~ ^[0-9]+$ ]]; then
74	echo "❌ Error: --max-iterations must be a positive integer or 0, got: $2" >&2
75	echo "" >&2
76	echo " Valid examples:" >&2
77	echo " --max-iterations 10" >&2
78	echo " --max-iterations 50" >&2
79	echo " --max-iterations 0 (unlimited)" >&2
80	echo "" >&2
81	echo " Invalid: decimals (10.5), negative numbers (-5), text" >&2
82	exit 1
83	fi
84	MAX_ITERATIONS="$2"
85	shift 2
86	;;
87	--completion-promise)
88	if [[ -z "${2:-}" ]]; then
89	echo "❌ Error: --completion-promise requires a text argument" >&2
90	echo "" >&2
91	echo " Valid examples:" >&2
92	echo " --completion-promise 'DONE'" >&2
93	echo " --completion-promise 'TASK COMPLETE'" >&2
94	echo " --completion-promise 'All tests passing'" >&2
95	echo "" >&2
96	echo " You provided: --completion-promise (with no text)" >&2
97	echo "" >&2
98	echo " Note: Multi-word promises must be quoted!" >&2
99	exit 1
100	fi
101	COMPLETION_PROMISE="$2"
102	shift 2
103	;;
104	*)
105	# Non-option argument - collect all as prompt parts
106	PROMPT_PARTS+=("$1")
107	shift
108	;;
109	esac
110	done
111
112	# Join all prompt parts with spaces
113	PROMPT="${PROMPT_PARTS[*]}"
114
115	# Validate prompt is non-empty
116	if [[ -z "$PROMPT" ]]; then
117	echo "❌ Error: No prompt provided" >&2
118	echo "" >&2
119	echo " Ralph needs a task description to work on." >&2
120	echo "" >&2
121	echo " Examples:" >&2
122	echo " /ralph-loop Build a REST API for todos" >&2
123	echo " /ralph-loop Fix the auth bug --max-iterations 20" >&2
124	echo " /ralph-loop --completion-promise 'DONE' Refactor code" >&2
125	echo "" >&2
126	echo " For all options: /ralph-loop --help" >&2
127	exit 1
128	fi
129
130	# Create state file for stop hook (markdown with YAML frontmatter)
131	mkdir -p .claude
132
133	# Quote completion promise for YAML if it contains special chars or is not null
134	if [[ -n "$COMPLETION_PROMISE" ]] && [[ "$COMPLETION_PROMISE" != "null" ]]; then
135	COMPLETION_PROMISE_YAML="\"$COMPLETION_PROMISE\""
136	else
137	COMPLETION_PROMISE_YAML="null"
138	fi
139
140	cat > .claude/ralph-loop.local.md <<EOF
141	---
142	active: true
143	iteration: 1
144	max_iterations: $MAX_ITERATIONS
145	completion_promise: $COMPLETION_PROMISE_YAML
146	started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
147	---
148
149	$PROMPT
150	EOF
151
152	# Output setup message
153	cat <<EOF
154	🔄 Ralph loop activated in this session!
155
156	Iteration: 1
157	Max iterations: $(if [[ $MAX_ITERATIONS -gt 0 ]]; then echo $MAX_ITERATIONS; else echo "unlimited"; fi)
158	Completion promise: $(if [[ "$COMPLETION_PROMISE" != "null" ]]; then echo "${COMPLETION_PROMISE//\"/} (ONLY output when TRUE - do not lie!)"; else echo "none (runs forever)"; fi)
159
160	The stop hook is now active. When you try to exit, the SAME PROMPT will be
161	fed back to you. You'll see your previous work in files, creating a
162	self-referential loop where you iteratively improve on the same task.
163
164	To monitor: head -10 .claude/ralph-loop.local.md
165
166	⚠️ WARNING: This loop cannot be stopped manually! It will run infinitely
167	unless you set --max-iterations or --completion-promise.
168
169	🔄
170	EOF
171
172	# Output the initial prompt if provided
173	if [[ -n "$PROMPT" ]]; then
174	echo ""
175	echo "$PROMPT"
176	fi
177
178	# Display completion promise requirements if set
179	if [[ "$COMPLETION_PROMISE" != "null" ]]; then
180	echo ""
181	echo "═══════════════════════════════════════════════════════════"
182	echo "CRITICAL - Ralph Loop Completion Promise"
183	echo "═══════════════════════════════════════════════════════════"
184	echo ""
185	echo "To complete this loop, output this EXACT text:"
186	echo " <promise>$COMPLETION_PROMISE</promise>"
187	echo ""
188	echo "STRICT REQUIREMENTS (DO NOT VIOLATE):"
189	echo " ✓ Use <promise> XML tags EXACTLY as shown above"
190	echo " ✓ The statement MUST be completely and unequivocally TRUE"
191	echo " ✓ Do NOT output false statements to exit the loop"
192	echo " ✓ Do NOT lie even if you think you should exit"
193	echo ""
194	echo "IMPORTANT - Do not circumvent the loop:"
195	echo " Even if you believe you're stuck, the task is impossible,"
196	echo " or you've been running too long - you MUST NOT output a"
197	echo " false promise statement. The loop is designed to continue"
198	echo " until the promise is GENUINELY TRUE. Trust the process."
199	echo ""
200	echo " If the loop should stop, the promise statement will become"
201	echo " true naturally. Do not force it by lying."
202	echo "═══════════════════════════════════════════════════════════"
203	fi