Ralph

⠀⠀⠀⠀⠀⠀⣀⣤⣶⡶⢛⠟⡿⠻⢻⢿⢶⢦⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⢀⣠⡾⡫⢊⠌⡐⢡⠊⢰⠁⡎⠘⡄⢢⠙⡛⡷⢤⡀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⢠⢪⢋⡞⢠⠃⡜⠀⠎⠀⠉⠀⠃⠀⠃⠀⠃⠙⠘⠊⢻⠦⠀⠀⠀⠀⠀⠀
⠀⠀⢇⡇⡜⠀⠜⠀⠁⠀⢀⠔⠉⠉⠑⠄⠀⠀⡰⠊⠉⠑⡄⡇⠀⠀⠀⠀⠀⠀
⠀⠀⡸⠧⠄⠀⠀⠀⠀⠀⠘⡀⠾⠀⠀⣸⠀⠀⢧⠀⠛⠀⠌⡇⠀⠀⠀⠀⠀⠀
⠀⠘⡇⠀⠀⠀⠀⠀⠀⠀⠀⠙⠒⠒⠚⠁⠈⠉⠲⡍⠒⠈⠀⡇⠀⠀⠀⠀⠀⠀
⠀⠀⠈⠲⣆⠀⠀⠀⠀⠀⠀⠀⠀⣠⠖⠉⡹⠤⠶⠁⠀⠀⠀⠈⢦⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠈⣦⡀⠀⠀⠀⠀⠧⣴⠁⠀⠘⠓⢲⣄⣀⣀⣀⡤⠔⠃⠀⠀⠀⠀⠀
⠀⠀⠀⠀⣜⠀⠈⠓⠦⢄⣀⣀⣸⠀⠀⠀⠀⠁⢈⢇⣼⡁⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⢠⠒⠛⠲⣄⠀⠀⠀⣠⠏⠀⠉⠲⣤⠀⢸⠋⢻⣤⡛⣄⠀⠀⠀⠀⠀⠀⠀
⠀⠀⢡⠀⠀⠀⠀⠉⢲⠾⠁⠀⠀⠀⠀⠈⢳⡾⣤⠟⠁⠹⣿⢆⠀⠀⠀⠀⠀⠀
⠀⢀⠼⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣼⠃⠀⠀⠀⠀⠀⠈⣧⠀⠀⠀⠀⠀
⠀⡏⠀⠘⢦⡀⠀⠀⠀⠀⠀⠀⠀⠀⣠⠞⠁⠀⠀⠀⠀⠀⠀⠀⢸⣧⠀⠀⠀⠀
⢰⣄⠀⠀⠀⠉⠳⠦⣤⣤⡤⠴⠖⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢯⣆⠀⠀⠀
⢸⣉⠉⠓⠲⢦⣤⣄⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣠⣼⢹⡄⠀⠀
⠘⡍⠙⠒⠶⢤⣄⣈⣉⡉⠉⠉⠛⠛⠛⠛⠛⠛⢻⠉⠉⠉⢙⣏⣁⣸⠇⡇⠀⠀
⠀⢣⠀⠀⠀⠀⠀⠀⠉⠉⠉⠙⠛⠛⠛⠛⠛⠛⠛⠒⠒⠒⠋⠉⠀⠸⠚⢇⠀⠀
⠀⠀⢧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⠇⢤⣨⠇⠀
⠀⠀⠀⢧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤⢻⡀⣸⠀⠀⠀
⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢹⠛⠉⠁⠀⠀⠀
⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⢠⢄⣀⣤⠤⠴⠒⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀
⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠘⡆⠀⠀⠀⠀⠀
⠀⠀⠀⡎⠀⠀⠀⠀⠀⠀⠀⠀⢷⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀
⠀⠀⢀⡷⢤⣤⣀⣀⣀⣀⣠⠤⠾⣤⣀⡘⠛⠶⠶⠶⠶⠖⠒⠋⠙⠓⠲⢤⣀⠀
⠀⠀⠘⠧⣀⡀⠈⠉⠉⠁⠀⠀⠀⠀⠈⠙⠳⣤⣄⣀⣀⣀⠀⠀⠀⠀⠀⢀⣈⡇
⠀⠀⠀⠀⠀⠉⠛⠲⠤⠤⢤⣤⣄⣀⣀⣀⣀⡸⠇⠀⠀⠀⠉⠉⠉⠉⠉⠉⠁⠀

Iterative AI Development Loop Tool

Ralph implements the "Ralph Wiggum" technique for self-referential AI development loops using GitHub Copilot. It continuously feeds prompts to AI, monitoring for completion signals, with each iteration building on previous work until the task is done.

Important

While ralph works, he's highly experimental. I built this primarily to understand how to embed the Copilot CLI SDK. Feel free to use it, or as inspiration on how to integrate with the Copilot CLI SDK.

Features

✨ Iterative AI Loops - Run multiple AI iterations until task completion

⚙️ Flexible Configuration - Configure loops via command-line flags

🤖 GitHub Copilot Integration - Powered by GitHub Copilot SDK

📈 Real-time Event Streaming - Watch iteration progress and tool execution

⏱️ Timeout Controls - Prevent runaway loops with safety limits

🛠️ Tool Execution - AI can read files, run commands, and make changes

Quick Start

Installation

# From source (requires Go 1.22+)
go install github.com/JanDeDobbeleer/copilot-ralph/cmd/ralph@latest

# Or build from source
git clone https://github.com/JanDeDobbeleer/copilot-ralph.git
cd copilot-ralph
make build

Usage

# Run an AI development loop
ralph run "Add unit tests for the parser module"

# Use a Markdown file as the prompt
ralph run task_description.md

# With options
ralph run --max-iterations 5 --timeout 10m "Refactor authentication"

# Custom model and settings
ralph run \
  --model gpt-4-turbo \
  --promise "Task complete!" \
  --streaming=true \
  "Implement user authentication"

How It Works

1. Initialize - Ralph parses your prompt and configuration (max iterations, timeout)
2. Setup - Create SDK client and loop engine with system prompt
3. Listen - Start event listener to display progress in real-time
4. Loop - For each iteration:
   • Send prompt to Copilot AI
   • Stream AI response to stdout
   • Execute any tools the AI invokes (read files, run commands, etc.)
5. Complete - Loop exits when:
   • Max iterations reached ✓ Complete
   • Timeout exceeded ✗ Timeout
   • Error occurs ✗ Failed
   • User cancels (Ctrl+C) ✗ Cancelled
6. Summary - Display final status, iteration count, and duration

┌──────────────┐
│   Config &   │
│   Prompt     │
└──────┬───────┘
       │
       v
┌──────────────────┐      ┌────────────────┐
│  SDK Client      │─────>│  Copilot AI    │
│  Loop Engine     │      │  (per iteration)│
└──────┬───────────┘      └────────┬───────┘
       │                           │
       v                           v
┌──────────────────┐      ┌────────────────┐
│  Event Listener  │<─────│  Tools Execute │
│  (Display)       │      │  (file ops,etc)│
└──────┬───────────┘      └────────────────┘
       │                           │
       └───────────────────────────┘
              │
              v
         ✓ Complete (or timeout/error)

Commands

ralph run

Run an AI development loop.

# Direct prompt
ralph run "Add comprehensive error handling"

# Using a Markdown file as prompt
ralph run task_description.md

# With flags
ralph run \
  --max-iterations 20 \
  --timeout 1h \
  --model gpt-4-turbo \
  --log-level debug \
  "Implement user authentication"

# Dry run (show what would happen)
ralph run --dry-run "Refactor database layer"

# With custom system message
ralph run \
  --system-prompt "You are an expert Go developer" \
  --system-prompt-mode replace \
  "Optimize the code"

Available flags:

• --max-iterations, -m - Maximum loop iterations (default: 10)
• --timeout, -t - Maximum loop runtime (default: 30m)
• --promise - Completion promise phrase (default: "I'm special!")
• --model - AI model to use (default: gpt-4)
• --working-dir - Working directory (default: current)
• --log-level - Log level: debug, info, warn, error (default: info)
• --streaming - Enable streaming responses (default: true)
• --system-prompt - Custom system message
• --system-prompt-mode - append or replace (default: append)
• --dry-run - Show configuration without running

ralph version

Show version information.

ralph version

Configuration

Ralph is configured entirely through command-line flags with sensible defaults. All settings can be customized per run:

• Command-line flags - All configuration via CLI flags
• Default values - Sensible defaults for all options

Common flags:

• --max-iterations 10 - Maximum iterations before stopping
• --timeout 30m - Maximum runtime
• --model gpt-4 - AI model to use
• --promise "I'm special!" - Completion phrase
• --log-level info - Logging verbosity
• --streaming true - Enable streaming responses

Run ralph run --help for all available options.

Development

Prerequisites

• Go 1.24 or later
• GitHub Copilot access
• Git

Building

# Install dependencies
go mod download

# Build
make build

# Run tests
make test

# Run linter
make lint

# All checks (tidy, lint, test, build)
make all

Architecture

Ralph is organized into distinct layers:

CLI Layer (cmd/ralph, internal/cli)
    │ Commands, flags, validation
    ↓
TUI Layer (internal/tui)
    │ Terminal UI, user interaction
    ↓
Core Layer (internal/core)
    │ Loop engine, business logic
    ↓
SDK Layer (internal/sdk)
    │ Copilot integration
    ↓
GitHub Copilot API

See AGENTS.md for detailed architecture documentation.

Contributing

Contributions are welcome! Please:

1. Read AGENTS.md for development guidelines
2. Follow the spec-driven development approach
3. Ensure tests pass and code is formatted
4. Submit a pull request with clear description

License

MIT License - see LICENSE for details

Acknowledgments

• Inspired by the Ralph Wiggum plugin for Claude
• Built with GitHub Copilot SDK
• UI powered by Charm Bracelet tools

Project Status

🚧 Early Development - Ralph is in active development. Core features are being implemented.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions