Ralph Steering

Autonomous AI development loop for Claude Code. Run Claude iteratively to complete complex, multi-step tasks — with an interactive terminal UI, cost tracking, and automatic rate-limit handling.

How It Works

Ralph reads a prompt file (default: PROMPT.md) and spawns Claude Code in a loop. Each iteration re-reads the prompt, runs Claude with --dangerously-skip-permissions, and monitors the output for a configurable exit signal (default: RALPH_DONE). When Claude outputs the signal, the loop stops.

This lets you define a task in a prompt file and let Claude work through it autonomously across multiple iterations — useful for large refactors, migrations, multi-step builds, and other work that exceeds a single Claude turn.

Installation

Prerequisites

• Claude Code CLI installed and authenticated
• Node.js >= 18 or Bun

Global install

npm install -g ralph-steering

Per-project install

npm install --save-dev ralph-steering
# or
bun add -d ralph-steering

Quick Start

1. Create a PROMPT.md in your project root:

Read TASKS.json and implement the next pending task.
Commit when done.

When ALL tasks are complete, output on its own line:

RALPH_DONE

2. Run Ralph:

# Global install
ralph-steering

# Per-project (npx)
npx ralph-steering

# Or with bun (from source)
bun run dev

Ralph will launch its interactive TUI, start Claude, and loop until it sees RALPH_DONE in the output.

Usage

ralph-steering [options]

Options:
  -m, --max-iterations <n>   Maximum iterations before stopping  (default: 200)
  --model <model>            Claude model to use                  (default: "opus")
  -p, --prompt-file <file>   Prompt file path                     (default: "PROMPT.md")
  -s, --exit-signal <signal> Exit signal to watch for             (default: "RALPH_DONE")
  --rate-limit-delay <ms>    Delay after rate limit in ms         (default: 60000)
  -v, --verbose              Enable verbose logging
  --cwd <dir>                Working directory for Claude process
  --mock                     Use mock Claude for testing
  --mock-scenario <name>     Mock scenario name
  -h, --help                 Show help

Examples

# Use Sonnet model with custom prompt
ralph-steering --model sonnet -p MIGRATION_PROMPT.md

# Limit to 10 iterations
ralph-steering -m 10

# Run from a different directory
ralph-steering --cwd ~/projects/my-app

# Test without Claude API (mock mode)
ralph-steering --mock --mock-scenario successful_completion

Modes

TUI Mode (default)

Interactive terminal UI built with Ink:

• Real-time streaming log output with syntax highlighting
• Status bar showing iteration count, token usage, cost, and elapsed time
• Interactive input — type messages and send them to the running Claude process
• Ctrl+C to gracefully stop

ralph-steering

Legacy Mode

Simple console output with colored logging, no interactive UI:

ralph-legacy
# or
npx ralph-steering --legacy  # not yet supported, use ralph-legacy binary

Programmatic API

Use Ralph as a library in your own tools:

import { RalphLoop } from 'ralph-steering';

const loop = new RalphLoop({
  maxIterations: 50,
  model: 'sonnet',
  promptFile: 'PROMPT.md',
  exitSignal: 'DONE',
  cwd: '/path/to/project',
});

await loop.run();

Or use the TUI renderer directly:

import { renderTui } from 'ralph-steering';

await renderTui({
  maxIterations: 100,
  model: 'opus',
  promptFile: 'PROMPT.md',
  exitSignal: 'RALPH_DONE',
  rateLimitDelay: 60000,
  verbose: false,
  cwd: process.cwd(),
  mockMode: false,
});

Writing Effective Prompts

Your PROMPT.md is re-read every iteration, so you can edit it while Ralph is running. A good prompt should:

1. Define the task — what Claude should do each iteration
2. Point to context — reference task files, docs, or code locations
3. Include the exit signal — tell Claude when and how to signal completion

Example for a task-driven workflow:

Read TASKS.json and pick the next task with status "todo".
Implement it fully, including tests. Commit your changes.
Update the task status to "done" in TASKS.json.

When ALL tasks are done, output:

RALPH_DONE

Mock Mode

Test your setup without making API calls:

ralph-steering --mock --mock-scenario successful_completion

Available scenarios:

• successful_completion — 3 iterations, completes normally
• with_rate_limit — simulates a rate limit and recovery
• with_error_recovery — simulates an error and retry

Development

git clone https://github.com/YuriiHoliuk/ralph-steering.git
cd ralph-steering
bun install

# Run in dev mode (TypeScript directly)
bun run dev

# Build for distribution
bun run build

# Type check
bun run typecheck

License

MIT