### Install Ralph Extension and Configure Gemini CLI

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Installs the Ralph extension from GitHub with auto-update and configures the Gemini CLI settings to enable hooks and include the extension directory. This is the initial setup required to use Ralph.

```bash
# Install Ralph extension with auto-update
gemini extensions install https://github.com/gemini-cli-extensions/ralph --auto-update

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

# Launch Gemini CLI in sandbox mode with auto-approval
gemini -s -y
```

--------------------------------

### Install Ralph Extension

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Install the Ralph extension directly from GitHub. Use --auto-update for automatic updates.

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

--------------------------------

### Start a Ralph Loop Task

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Initiate a development loop with a task description. Use --max-iterations to set a limit on the number of loops.

```bash
/ralph:loop "Build a Python CLI task manager with full test coverage." --max-iterations 10
```

--------------------------------

### Start Ralph Loop with Custom Iteration Limit

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Starts an autonomous development loop with a custom maximum iteration limit. This is useful for tasks requiring more or fewer steps than the default.

```bash
/ralph:loop "Refactor the authentication module." --max-iterations 20
```

--------------------------------

### Start Ralph Loop with Completion Promise

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Starts an autonomous development loop that terminates only when the agent explicitly outputs the specified completion promise text. This allows for explicit task completion criteria.

```bash
/ralph:loop "Build a REST API for todos. When all CRUD endpoints are working and all tests pass, you're complete." --max-iterations 10 --completion-promise "TASK_COMPLETE"
```

--------------------------------

### Start Ralph Loop with Default Iterations

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Initiates an autonomous development loop with the specified task using the default maximum of 5 iterations. Ensure the prompt clearly defines the task for the AI agent.

```bash
/ralph:loop "Build a Python CLI task manager with full test coverage."
```

--------------------------------

### Ralph State File Example

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Illustrates the structure of the `state.json` file used by Ralph to maintain loop status, iteration counts, completion promises, and the original prompt. This file is located at `.gemini/ralph/state.json`.

```json
{
    "active": true,
    "current_iteration": 1,
    "max_iterations": 10,
    "completion_promise": "TASK_COMPLETE",
    "original_prompt": "Build a REST API for todos.",
    "started_at": "2024-01-15T10:30:00Z"
}
```

--------------------------------

### Prompt for Self-Correction with Completion Promise

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Structure prompts to guide the agent through a cycle of work, verification, and debugging, using a completion promise for the final output.

```text
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>'.
```

--------------------------------

### Display Ralph Help Information

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Shows detailed usage instructions for all Ralph commands and their available options. This is useful for understanding how to use Ralph effectively.

```bash
/ralph:help
```

--------------------------------

### Configure Gemini CLI for Ralph Hooks

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Enable hooks and configure context inclusion in ~/.gemini/settings.json to allow Gemini CLI to access Ralph's scripts and hook logic.

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

--------------------------------

### Uninstall Ralph Extension

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Run this command to uninstall the Ralph extension. Remember to manually remove the entry from `~/.gemini/settings.json` to prevent startup errors.

```bash
# Uninstall Ralph extension
gemini extensions uninstall ralph
```

```json
# IMPORTANT: Manually remove from ~/.gemini/settings.json
# Remove this entry to prevent CLI startup errors:
{
  "context": {
    "includeDirectories": ["~/.gemini/extensions/ralph"]
  }
}
```

--------------------------------

### Run Gemini CLI in Sandbox Mode with YOLO

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Launch the Gemini CLI in sandbox mode (-s) with YOLO enabled (-y) to prevent constant prompts for tool execution during a Ralph loop.

```bash
gemini -s -y
```

--------------------------------

### Remove Extension Context Entry

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Manually remove this configuration block from ~/.gemini/settings.json after uninstallation to avoid startup errors.

```json
  "context": {
    "includeDirectories": ["~/.gemini/extensions/ralph"]
  }
```

--------------------------------

### TDD Workflow with Promise-Based Completion

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Initiates a Test-Driven Development (TDD) loop where the agent follows specific steps and uses a completion promise to signal when tests have passed. This enforces a structured development process.

```bash
/ralph:loop "Implement user registration:
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.
5. Refactor for clarity and efficiency.
6. When complete, output '<promise>TESTS_PASSED</promise>'." --completion-promise "TESTS_PASSED"
```

--------------------------------

### Configure Allowed Git Operations for Security

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Defines security settings for Ralph by specifying allowed and excluded git operations. This prevents accidental destructive actions, such as `git push`, during autonomous loops.

```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)"
    ]
  }
}
```

--------------------------------

### Continue Loop - Deny Exit

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Use this response to deny an exit request and restart the loop with the original prompt. Setting `clearContext: true` clears the agent's memory between iterations.

```bash
# Continue loop - deny exit and restart with original prompt
{
  "decision": "deny",
  "reason": "Original task prompt here",
  "systemMessage": "🔄 Ralph is starting iteration 2...",
  "hookSpecificOutput": {
    "clearContext": true
  }
}
```

--------------------------------

### Set Max Iterations for Ralph Loop

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Use --max-iterations as a safety net to prevent infinite loops by setting a hard limit on the number of iterations.

```bash
# Set a reasonable iteration limit
/ralph:loop "Attempt to refactor the authentication module." --max-iterations 20
```

--------------------------------

### Stop on Completion Promise

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Use this response to allow the loop to stop when a completion promise is found. The `continue` field should be set to `false`.

```bash
# Stop on completion promise
{
  "decision": "allow",
  "continue": false,
  "stopReason": "✅ Ralph found the completion promise: TASK_COMPLETE",
  "systemMessage": "✅ Ralph found the completion promise: TASK_COMPLETE"
}
```

--------------------------------

### Stop on Iteration Limit

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Use this response to allow the loop to stop when the iteration limit is reached. The `continue` field should be set to `false`.

```bash
# Stop on iteration limit
{
  "decision": "allow",
  "continue": false,
  "stopReason": "✅ Ralph has reached the iteration limit.",
  "systemMessage": "✅ Ralph has reached the iteration limit."
}
```

--------------------------------

### Define Completion Promise for Ralph Loop

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Specify a completion promise to terminate the Ralph loop when the agent outputs the defined text, ensuring clear completion criteria.

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

--------------------------------

### Uninstall Ralph Extension

Source: https://github.com/gemini-cli-extensions/ralph/blob/main/README.md

Execute the command to remove the Ralph extension from the Gemini CLI.

```bash
gemini extensions uninstall ralph
```

--------------------------------

### AfterAgent Hook Configuration for Ralph Loop

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Configures the `AfterAgent` hook to intercept agent exits and manage the Ralph loop. It specifies the hook command to run, which is responsible for validating prompts, checking iteration limits, and detecting completion promises.

```json
{
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "ralph-loop",
            "type": "command",
            "command": "${extensionPath}/hooks/stop-hook.sh",
            "description": "The Ralph infinite loop mechanism"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Cancel Active Ralph Loop

Source: https://context7.com/gemini-cli-extensions/ralph/llms.txt

Stops an ongoing Ralph autonomous development loop and cleans up all associated state files. Use this to manually terminate a loop.

```bash
/ralph:cancel
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.