Ralph

A bash function for running Claude CLI in a loop with automatic escape phrase detection.

Features

• Run Claude prompts multiple times in succession
• Automatic stopping when an escape phrase is detected in output
• Configurable timeout per iteration
• Docker container mode (default) or local mode running directly on the host
• Graceful interrupt handling (single Ctrl-C waits for current job, double Ctrl-C kills immediately)

Installation

Add the following to your ~/.bashrc or ~/.bash_profile:

source /path/to/ralph/bash_ralph.sh

Then reload your shell:

source ~/.bashrc

Usage

echo "your prompt here" | ralph <count> <escape_phrase> [options] [claude_args...]

Required Arguments

• count - Number of iterations to run
• escape_phrase - Phrase to detect in output to stop early

Options

• --timeout <seconds> - Timeout per iteration (default: 600 seconds)
• --local - Run Claude directly on the host instead of in a Docker container

Examples

Run a prompt 5 times, stopping early if "DONE" appears in the output:

echo "Write a haiku about coding" | ralph 5 "DONE"

Run with a custom timeout of 5 minutes:

echo "Solve this complex problem" | ralph 10 "SOLUTION FOUND" --timeout 300

Run in local mode (without Docker):

echo "Quick task" | ralph 3 "COMPLETE" --local

Pass additional arguments to Claude:

echo "Help me with this" | ralph 5 "FINISHED" --model claude-3-opus

Docker Setup

By default, ralph runs Claude inside a Docker container using ~/git/claude-container/docker-compose.yml. If this file doesn't exist, ralph automatically falls back to local mode.

The code to build the optional container can be found at https://github.com/Tipmethewink/claude-container

To use the containerized mode, ensure you have:

1. Docker and Docker Compose installed
2. A valid docker-compose.yml at ~/git/claude-container/docker-compose.yml

Interrupt Handling

• Single Ctrl-C: Waits for the current iteration to complete, then stops
• Double Ctrl-C: Immediately kills the current job and any running containers