What is Ralph?

Ralph is a development methodology where an AI agent receives the same prompt repeatedly until it completes a task. Each iteration, the AI sees its previous work in files and git history, enabling self-correction and incremental progress.

This package provides a CLI-only implementation, optimized for local control and speed.

✨ Key Features

• Robust Loop Logic: Handles state persistence, history tracking, and error recovery.
• Parallel Subtasks: Run multiple agents simultaneously on different tasks with full Git Worktree isolation.
• Project Configuration: Save defaults in .ralph/ralph.config.json (auto-initialized if missing).
• Global Rules: Auto-injects AGENTS.md, RULES.md, or .ralph/rules.md into context.
• Class-Based Architecture: Refactored for maintainability and extensibility (RalphLoop, ParallelExecutor).
• Detailed History: Tracks tool usage, files modified, and Struggle Detection to suggest when to intervene.
• Tasks Mode: Structured task tracking with subtask support and progress visualization.

Installation (Local Development)

This project is designed to run with Bun.

Option 1: Run directly

# Run from the project root
bun ralph.ts "Your prompt here"

Option 2: Link globally

# In the project root
bun install
bun link

# Now you can use 'ralph' anywhere
ralph --version

Quick Start

1. Simple Loop

ralph "Create a hello.txt file. Output <promise>DONE</promise> when complete." \
  --max-iterations 5

2. Parallel Execution (🚀)

Run multiple independent tasks simultaneously. Each worker runs in an isolated Git Worktree to prevent conflicts.

ralph --parallel \
  "Refactor login.ts" \
  "Update styles.css" \
  "Write unit tests" \
  --max-parallel 3

3. Advanced Parallel Execution

ralph --parallel \
  "Mejora los estilos del gráfico PnL" \
  "Añade animaciones al gráfico" \
  "Optimiza el rendimiento del renderizado" \
  --max-parallel 3 \
  --max-iterations 10 \
  --verbose-tools \
  --agent opencode \
  --model github-copilot/grok-code-fast-1

4. Tasks Mode

Work through a checklist in .ralph/ralph-tasks.md. In this mode, the prompt serves as the "Main Goal", while the file dictates the specific steps.

# 1. First, verify or create your task list in .ralph/ralph-tasks.md
- [ ] Set up database
- [ ] Create API endpoints

# 2. Run Ralph with a main goal prompt
ralph "Complete all backend tasks" --tasks

Configuration

Project Config

Initialize or edit the configuration file:

ralph --init-config

This creates .ralph/ralph.config.json where you can set defaults like agent, model, and auto-commit behavior. Ralph also looks for .ralph.config.json, .ralph.json, or ralph.config.json in the root.

Global Rules

Ralph automatically looks for these files in your project root and injects them into the AI's context:

• AGENTS.md
• RULES.md
• .ralph/rules.md

Context Injection

You can add manual hints or context mid-loop (for the next iteration):

ralph --add-context "Focus on the auth module first and use the new API client."

CLI Reference

Commands

• --status: Show current loop status, history, and struggle indicators.
• --status --tasks: Show status including the current task list.
• --add-context TEXT: Add context for the next iteration.
• --clear-context: Clear any pending context.
• --list-tasks: Display the current task list with indices.
• --add-task "desc": Add a new task to the list.
• --remove-task N: Remove task at index N.
• --init-config: Create a sample config file.

Execution Control

• prompts...: The task description (or subtasks in parallel mode).
• --tasks / -t: Enable Tasks Mode (reads .ralph/ralph-tasks.md).
• --prompt-file <path>: Read prompt from a file.
• --max-iterations N: Limit the number of loops (default: 10).
• --min-iterations N: Force a minimum number of loops (default: 1).
• --parallel: Enable parallel execution mode.
• --max-parallel N: Max concurrent workers (default: 2).

Agent & Model

• --agent opencode|claude-code|codex: Select AI agent (default: opencode).
• --model MODEL: Specify model (e.g., anthropic/claude-3-5-sonnet).

Flags

• --verbose-tools: Show every tool call (disables compact summary).
• --stream / --no-stream: Enable/disable streaming output.
• --no-commit: Disable auto-commit after each iteration.
• --no-plugins: Disable non-auth OpenCode plugins.
• --allow-all: Auto-approve all tool permissions (default: on).
• --no-allow-all: Require interactive permission prompts.

Development

Project Structure

The codebase is modular and class-based:

• src/loop.ts: Main logic for the RalphLoop class.
• src/parallel.ts: ParallelExecutor class for git worktree isolation.
• src/cli.ts: Argument parsing and command dispatch.
• src/prompt.ts: Prompt building and context/rules injection.
• src/agents.ts: Agent configurations and environment setup.
• src/tasks.ts: Logic for task parsing and progress tracking.
• src/project-config.ts: Configuration file discovery and merging.
• src/state.ts & src/history.ts: Persistence and tracking.

Running Tests

bun test

License

MIT