JanDeDobbeleer/copilot-ralph

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