Skip to content

Commit b6494bb

Browse files
evanoteroevanotero
committed
Update readme
1 parent aff03c1 commit b6494bb

1 file changed

Lines changed: 147 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 147 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,147 @@
1-
# ralph
1+
# Ralph 🔄
2+
3+
Ralph is a self-referential development loop for the Gemini CLI. It allows an agent to iteratively work on a task, self-correcting and refining its output over multiple turns without manual user intervention.
4+
5+
### Core Concept
6+
7+
The loop happens **across agent turns**, explicitly controlled by the extension's hook.
8+
9+
1. **You run ONCE**: `/ralph:loop "Your task description" --completion-promise "DONE"`
10+
2. **Gemini CLI works**: The agent performs actions (modifies files, runs tests).
11+
3. **Hook intercepts**: When the agent finishes its turn, the `AfterAgent` hook intercepts the exit.
12+
4. **Loop Continuation**: The hook evaluates state (max iterations, promises) and instructs the CLI to start a new turn using the **original prompt** and clears the agent's memory from the previous turn.
13+
5. **Repeat**: This continues autonomously until completion (max iterations, promises) or user interruption.
14+
15+
The `AfterAgent` hook in `hooks/stop-hook.sh` creates a **self-referential feedback loop** where:
16+
- **Stable Context & No Compaction**: The prompt never changes between iterations, and the **previous turn's conversational context is cleared**. This forces the agent to rely on the current state of the files rather than potentially stale or "compacted" chat history, ensuring maximum focus and reliability.
17+
- **Persistent State**: The agent's previous work persists in files and git history.
18+
- **Autonomous Improvement**: Each iteration allows the agent to see the current state of the codebase and improve upon its past work.
19+
- **Ghost Protection**: If you interrupt the loop and start a new task, the hook detects the prompt mismatch and silently cleans up so it doesn't hijack your new conversation.
20+
21+
Inspired by Geoffrey Huntley's article *[Ralph](https://ghuntley.com/ralph/)* this extension provides a robust framework for persistent, multi-turn agentic workflows.
22+
23+
## Installation
24+
25+
Install the extension directly from GitHub:
26+
27+
```bash
28+
gemini extensions install https://github.com/gemini-cli-extensions/ralph --auto-update
29+
```
30+
31+
## Configuration
32+
33+
To use Ralph, you must enable hooks and preview features in your `~/.gemini/settings.json`:
34+
35+
```json
36+
{
37+
"hooksConfig": {
38+
"enabled": true
39+
},
40+
"context": {
41+
"includeDirectories": ["~/.gemini/extensions/ralph"]
42+
}
43+
}
44+
```
45+
46+
> **Note**: `includeDirectories` is required so that the Gemini CLI can access and execute Ralph's internal scripts (`setup.sh`, `cancel.sh`) and hook logic located in the extension's installation directory.
47+
48+
## Usage
49+
50+
Start a loop by using the `/ralph:loop` command followed by your task.
51+
52+
```bash
53+
/ralph:loop "Build a Python CLI task manager with full test coverage." --max-iterations 10
54+
```
55+
56+
### Options
57+
58+
- `--max-iterations <N>`: Set a hard limit on how many times Ralph will loop (Default: 5).
59+
- `--completion-promise <TEXT>`: Ralph will watch the agent's output. The loop will terminate immediately if the agent outputs `<promise>TEXT</promise>`.
60+
61+
### Manual Controls
62+
63+
- `/ralph:cancel`: Stops an active loop and cleans up all state files.
64+
- `/ralph:help`: Displays detailed usage information and configuration tips.
65+
66+
## Prompt Writing Best Practices
67+
68+
The success of the Ralph technique depends heavily on well-crafted prompts.
69+
70+
### 1. Clear Completion Criteria
71+
72+
Provide a clear, verifiable definition of "done." The `--completion-promise` is crucial for this.
73+
74+
**Good:**
75+
```bash
76+
/ralph:loop "Build a REST API for todos. When all CRUD endpoints are working and all tests pass with >80% coverage, you're complete." --completion-promise "TASK_COMPLETE"
77+
```
78+
79+
### 2. Use Safety Hatches
80+
81+
Always use `--max-iterations` as a safety net to prevent infinite loops if a task is unclear or impossible.
82+
83+
```bash
84+
# Set a reasonable iteration limit
85+
/ralph:loop "Attempt to refactor the authentication module." --max-iterations 20
86+
```
87+
88+
### 3. Encourage Self-Correction
89+
90+
Structure your prompt to guide the agent through a cycle of work, verification, and debugging.
91+
92+
**Good:**
93+
```text
94+
Implement feature X by following TDD:
95+
1. Write failing tests for the feature.
96+
2. Implement the code to make the tests pass.
97+
3. Run the test suite.
98+
4. If any tests fail, analyze the errors and debug the code.
99+
5. Refactor for clarity and efficiency.
100+
6. Repeat until all tests are green.
101+
7. When complete, output the phrase '<promise>TESTS_PASSED</promise>'.
102+
```
103+
104+
## Launch Safely 🛡️
105+
106+
**Always run in sandbox mode for safety.** Enabling YOLO mode (`-y`) prevents constant prompts for tool execution during the loop:
107+
108+
```bash
109+
gemini -s -y
110+
```
111+
112+
### Recommended Security Settings
113+
114+
To prevent the agent from accidentally pushing code or performing destructive git operations during a loop, we recommend explicitly defining allowed tools in your project's `.gemini/settings.json`:
115+
116+
```json
117+
{
118+
"tools": {
119+
"exclude": ["run_shell_command(git push)"],
120+
"allowed": [
121+
"run_shell_command(git commit)",
122+
"run_shell_command(git add)",
123+
"run_shell_command(git diff)",
124+
"run_shell_command(git status)"
125+
]
126+
}
127+
}
128+
```
129+
130+
## Future Ideas 🚀
131+
132+
- **Rich Task Lists & Specs**: Support for structured specification files and rich task lists with metadata (priority, dependencies) per task.
133+
- **Iteration Progress Log**: Maintain a single, persistent progress file that is appended to in each iteration to track the agent's reasoning over time.
134+
- **Multi-Agent Orchestration**: Coordinate multiple specialized Ralph loops working on different parts of a larger system.
135+
- **Git-Native Loops**: Require the use of Git for every iteration, ensuring that the agent commits work incrementally and maintains a clean working directory before proceeding.
136+
- **Stricter Iteration Boundaries**: Implement more formal rules for when an iteration is considered "complete" (e.g., must pass a specific linter or test suite before the next turn is allowed).
137+
- **Clean State Enforcement**: Automatically revert or clean up temporary files/artifacts at the end of each iteration to prevent state pollution.
138+
139+
## Special Thanks
140+
141+
- **Geoffrey Huntley**: For the original ["Ralph Wiggum" technique]((https://ghuntley.com/ralph/) and the fundamental insight that "Ralph is a Bash loop."
142+
- **Anthropic Engineering**: For their research on [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), which informs the design of stable agentic loops.
143+
- **Inspiration & Reference Implementations**:
144+
- [galz10/pickle-rick-extension](https://github.com/galz10/pickle-rick-extension)
145+
- [AsyncFuncAI/ralph-wiggum-extension](https://github.com/AsyncFuncAI/ralph-wiggum-extension)
146+
- [jackwotherspoon/gemini-cli-ralph-wiggum](https://github.com/jackwotherspoon/gemini-cli-ralph-wiggum)
147+
- [evanotero/gemini-cli-ralph-wiggum](https://github.com/evanotero/gemini-cli-ralph-wiggum)

0 commit comments

Comments
 (0)