Skip to content
Back to search

ralph

SkillWorks with Gemini CLIGitHub

Gemini CLI extension for Ralph loops

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gemini-cli-extensions--ralph/badge.svg)](/listings/gemini-cli-extensions--ralph)

HTML

<a href="/listings/gemini-cli-extensions--ralph"><img src="/api/listings/gemini-cli-extensions--ralph/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the extension directly from GitHub:

gemini extensions install https://github.com/gemini-cli-extensions/ralph --auto-update

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 167 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Ralph 🔄
  2. 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.
  3. ### Core Concept
  4. The loop happens **across agent turns**, explicitly controlled by the extension's hook.
  5. 1. **You run ONCE**: `/ralph:loop "Your task description" --completion-promise "DONE"`
  6. 2. **Gemini CLI works**: The agent performs actions (modifies files, runs tests).
  7. 3. **Hook intercepts**: When the agent finishes its turn, the `AfterAgent` hook intercepts the exit.
  8. 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.
  9. 5. **Repeat**: This continues autonomously until completion (max iterations, promises) or user interruption.
  10. The `AfterAgent` hook in `hooks/stop-hook.sh` creates a **self-referential feedback loop** where:
  11. - **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.
  12. - **Persistent State**: The agent's previous work persists in files and git history.
  13. - **Autonomous Improvement**: Each iteration allows the agent to see the current state of the codebase and improve upon its past work.
  14. - **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.
  15. Inspired by Geoffrey Huntley's article *[Ralph](https://ghuntley.com/ralph/)* this extension provides a robust framework for persistent, multi-turn agentic workflows.
  16. ## Installation
  17. Install the extension directly from GitHub:
  18. ```bash
  19. gemini extensions install https://github.com/gemini-cli-extensions/ralph --auto-update
  20. ```
  21. ## Configuration
  22. To use Ralph, you must enable hooks and preview features in your `~/.gemini/settings.json`:
  23. ```json
  24. {
  25. "hooksConfig": {
  26. "enabled": true
  27. },
  28. "context": {
  29. "includeDirectories": ["~/.gemini/extensions/ralph"]
  30. }
  31. }
  32. ```
  33. > **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.
  34. ## Usage
  35. Start a loop by using the `/ralph:loop` command followed by your task.
  36. ```bash
  37. /ralph:loop "Build a Python CLI task manager with full test coverage." --max-iterations 10
  38. ```
  39. ### Options
  40. - `--max-iterations <N>`: Set a hard limit on how many times Ralph will loop (Default: 5).
  41. - `--completion-promise <TEXT>`: Ralph will watch the agent's output. The loop will terminate immediately if the agent outputs `<promise>TEXT</promise>`.
  42. ### Manual Controls
  43. - `/ralph:cancel`: Stops an active loop and cleans up all state files.
  44. - `/ralph:help`: Displays detailed usage information and configuration tips.
  45. ## Prompt Writing Best Practices
  46. The success of the Ralph technique depends heavily on well-crafted prompts.
  47. ### 1. Clear Completion Criteria
  48. Provide a clear, verifiable definition of "done." The `--completion-promise` is crucial for this.
  49. **Good:**
  50. ```bash
  51. /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"
  52. ```
  53. ### 2. Use Safety Hatches
  54. Always use `--max-iterations` as a safety net to prevent infinite loops if a task is unclear or impossible.
  55. ```bash
  56. # Set a reasonable iteration limit
  57. /ralph:loop "Attempt to refactor the authentication module." --max-iterations 20
  58. ```
  59. ### 3. Encourage Self-Correction
  60. Structure your prompt to guide the agent through a cycle of work, verification, and debugging.
  61. **Good:**
  62. ```text
  63. Implement feature X by following TDD:
  64. 1. Write failing tests for the feature.
  65. 2. Implement the code to make the tests pass.
  66. 3. Run the test suite.
  67. 4. If any tests fail, analyze the errors and debug the code.
  68. 5. Refactor for clarity and efficiency.
  69. 6. Repeat until all tests are green.
  70. 7. When complete, output the phrase '<promise>TESTS_PASSED</promise>'.
  71. ```
  72. ## Launch Safely 🛡️
  73. **Always run in sandbox mode for safety.** Enabling YOLO mode (`-y`) prevents constant prompts for tool execution during the loop:
  74. ```bash
  75. gemini -s -y
  76. ```
  77. ### Recommended Security Settings
  78. 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`:
  79. ```json
  80. {
  81. "tools": {
  82. "exclude": ["run_shell_command(git push)"],
  83. "allowed": [
  84. "run_shell_command(git commit)",
  85. "run_shell_command(git add)",
  86. "run_shell_command(git diff)",
  87. "run_shell_command(git status)"
  88. ]
  89. }
  90. }
  91. ```
  92. ## Uninstallation
  93. To uninstall Ralph, run:
  94. ```bash
  95. gemini extensions uninstall ralph
  96. ```
  97. ### ⚠️ IMPORTANT: Cleanup Required
  98. After uninstalling, you **MUST** manually remove the following entry from your `~/.gemini/settings.json` file:
  99. ```json
  100. "context": {
  101. "includeDirectories": ["~/.gemini/extensions/ralph"]
  102. }
  103. ```
  104. **If you fail to do this, the Gemini CLI will encounter an error on startup (as it will attempt to read a directory that no longer exists) and may not be able to finish initializing.**
  105. ## Future Ideas 🚀
  106. - **Rich Task Lists & Specs**: Support for structured specification files and rich task lists with metadata (priority, dependencies) per task.
  107. - **Iteration Progress Log**: Maintain a single, persistent progress file that is appended to in each iteration to track the agent's reasoning over time.
  108. - **Multi-Agent Orchestration**: Coordinate multiple specialized Ralph loops working on different parts of a larger system.
  109. - **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.
  110. - **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).
  111. - **Clean State Enforcement**: Automatically revert or clean up temporary files/artifacts at the end of each iteration to prevent state pollution.
  112. ## Special Thanks
  113. - **Geoffrey Huntley**: For the original ["Ralph Wiggum" technique]((https://ghuntley.com/ralph/) and the fundamental insight that "Ralph is a Bash loop."
  114. - **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.
  115. - **Inspiration & Reference Implementations**:
  116. - [galz10/pickle-rick-extension](https://github.com/galz10/pickle-rick-extension)
  117. - [AsyncFuncAI/ralph-wiggum-extension](https://github.com/AsyncFuncAI/ralph-wiggum-extension)
  118. - [jackwotherspoon/gemini-cli-ralph-wiggum](https://github.com/jackwotherspoon/gemini-cli-ralph-wiggum)
  119. - [evanotero/gemini-cli-ralph-wiggum](https://github.com/evanotero/gemini-cli-ralph-wiggum)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.