DOCSEARCHbyAlgolia
Submit Docs

Ralph for Gemini CLI

repository·main·Indexed 43 days ago

https://github.com/gemini-cli-extensions/ralph

A self-referential development loop extension for the Gemini CLI that enables autonomous, multi-turn agentic workflows. Ralph uses an AfterAgent hook to reset conversational context while preserving file state, allowing agents to focus on the codebase. It includes the /ralph:loop command with options for --max-iterations and --completion-promise to control loop termination, as well as /ralph:cancel for session cleanup.

Tokens
2.3K
Snippets
12
Records
15
Agent score
56%

What's inside Ralph

  1. How the Ralph self-referential loop works

    main

    Ralph creates an autonomous development loop that operates across multiple agent turns using the AfterAgent hook.

    The Workflow:

    1. Initiation: You trigger a loop with /ralph:loop "task description".
    2. Execution: The agent performs actions (e.g., writing code, running tests).
    3. Interception: The AfterAgent hook intercepts the end of the turn.
    4. Reset & Repeat: The hook clears the agent's conversational memory (to prevent stale context/compaction) but keeps the prompt and the file state identical. It then instructs the CLI to start a new turn using the original prompt.
    5. Termination: The loop continues until the agent meets a --completion-promise, reaches --max-iterations, or is manually interrupted.

    Key Benefits:

    • Stable Context: By clearing chat history each turn, the agent focuses on the actual state of the files rather than a long, potentially confusing conversation history.
    • Persistent State: Changes made to files and git history persist across iterations.
    • Ghost Protection: If you start a new task manually, the hook detects the prompt mismatch and prevents the loop from hijacking your new session.
    /ralph:loop "Your task description" --completion-promise "DONE"

  2. Uninstall Ralph and cleanup

    main

    To uninstall Ralph, use the extension uninstall command.

    CRITICAL: You must manually remove the includeDirectories entry for Ralph from your ~/.gemini/settings.json. If you skip this, the Gemini CLI will error on startup because it will try to access a directory that no longer exists.

    gemini extensions uninstall ralph

  5. Best practices for writing Ralph prompts

    main

    To maximize the effectiveness of the Ralph loop, follow these three principles:

    1. Define Clear Completion Criteria

    Use the --completion-promise flag to give the agent a verifiable definition of 'done'. Example:

    /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"

    2. Use Safety Hatches

    Always set a --max-iterations limit to prevent infinite loops if a task becomes impossible or ambiguous. Example:

    /ralph:loop "Attempt to refactor the authentication module." --max-iterations 20

    3. Encourage Self-Correction

    Structure your prompt as a cycle of work, verification, and debugging (e.g., TDD). Example Prompt Structure:

    Implement feature X by following TDD:
1. Write failing tests for the feature.
2. Implement the code to make the tests pass.
3. Run the test suite.
4. If any tests fail, analyze the errors and debug the code.
5. Refactor for clarity and efficiency.
6. Repeat until all tests are green.
7. When complete, output the phrase '<promise>TESTS_PASSED</promise>'.

  6. Configure Ralph in settings.json

    main

    To enable Ralph, you must modify your ~/.gemini/settings.json to enable hooks and include the extension's directory in the context. Including the directory is mandatory so the CLI can access Ralph's internal scripts like setup.sh and cancel.sh.

    {
  "hooksConfig": {
    "enabled": true
  },
  "context": {
    "includeDirectories": ["~/.gemini/extensions/ralph"]
  }
}

  7. Restrict agent tools for security

    main

    To prevent the agent from performing destructive operations (like git push) during an autonomous loop, define allowed and excluded tools in your project's .gemini/settings.json.

    {
  "tools": {
    "exclude": ["run_shell_command(git push)"],
    "allowed": [
      "run_shell_command(git commit)",
      "run_shell_command(git add)",
      "run_shell_command(git diff)",
      "run_shell_command(git status)"
    ]
  }
}

  8. Reference: /ralph:loop options

    main

    Options available when using the /ralph:loop command:

    • --max-iterations <N>: Sets a hard limit on the number of loop iterations. (Default: 5)
    • --completion-promise <TEXT>: Defines a specific string the agent must output to terminate the loop. The loop ends if the agent outputs <promise>TEXT</promise>.

  11. Configure the Ralph loop via setup.sh arguments

    main

    When starting a Ralph loop, you can pass specific arguments to the initialization script (setup.sh) to define the loop's boundaries and exit conditions.

    ArgumentDescription
    --max-iterations <N>The maximum number of loop iterations allowed before the loop must stop.
    --completion-promise <TEXT>A specific text token that the agent must output to signal that the task is genuinely complete.

    Note: Arguments must be passed verbatim to the setup script.

    # Example: Limit to 5 iterations and require a specific completion token
ralph-loop --max-iterations 5 --completion-promise "TASK_FINISHED"

  12. Configure Ralph loop options

    main

    When starting a loop with /ralph:loop, you can use the following options to control the agent's behavior:

    • --max-iterations <N>: Sets a hard limit on the number of iterations the agent will perform. The default is 5.
    • --completion-promise <TEXT>: Defines a specific exit condition. The loop will only stop when the agent explicitly outputs the XML-style tag <promise>TEXT</promise>.
    # Example: Run for a maximum of 10 iterations
/ralph:loop "Refactor this code" --max-iterations 10

# Example: Stop only when the agent promises a specific outcome
/ralph:loop "Write a test suite" --completion-promise "tests complete"