ralph

ralph is an autonomous loop task runner that uses GitHub Copilot CLI to iteratively work on tasks until completion. It creates a feedback loop where Copilot learns from previous attempts and adjusts its approach accordingly.

Features

• Autonomous iteration: ralph runs GitHub Copilot in a loop, allowing it to learn from previous attempts
• Short-term memory: Each iteration has access to the history of what was already tried
• Task file support: Define tasks in markdown or text files
• Completion detection: Automatically stops when the task is marked as done
• Verbose mode: See detailed execution logs

Prerequisites

• Bash shell (Linux, macOS, or WSL on Windows)
• GitHub Copilot CLI

Installation

Quick Install

To install ralph system-wide (defauls to /usr/local/bin, requiring sudo):

make install

To install to a different location:

make install PREFIX=${HOME}/bin

Manual Installation

You can also run ralph directly without installing:

./src/ralph.bash [options] [subcommand]

Or create a symlink to the script:

ln -s "$(pwd)/src/ralph.bash" "/usr/local/bin/ralph"

Examples

Example 1: Create a new feature

ralph --verbose << 'EOF'
Create a function in src/math.js that:
1. Exports a function called 'isPrime'
2. Takes a number as input
3. Returns true if the number is prime, false otherwise
4. Includes proper error handling
EOF

Example 2: Fix bugs

echo "Fix all TODO comments in the codebase" | ralph --iterations 15

Example 3: Refactoring

ralph --file .ralph/refactor-task.md --verbose

Usage

Basic Usage

1. Initialize ralph in your project directory:

   ralph init

2. Create a task file in .ralph/tasks:

   echo "Create a function that calculates fibonacci numbers" > .ralph/tasks

3. Run ralph:

   ralph

Advanced Usage

Specify a custom task file

ralph --file my-tasks.md

Read task from stdin

echo "Fix all linting errors" | ralph

Set maximum iterations

ralph --iterations 20

Force re-run a completed task

ralph --force

Switch AI model

ralph -m gpt-5
# or
ralph --model gpt-4.1

Note: Model names supported depend on your installed GitHub Copilot CLI; check its documentation for available models.

Enable verbose output

ralph --verbose

Spec-Driven Development (SDD) Mode

SDD mode lets ralph iterate over a folder of structured spec files instead of a single flat task file. Each spec is processed independently with its own iteration history and completion sentinel.

How SDD mode activates

1. Explicit: pass -s <dir> / --specs <dir> to point at a specs folder
2. Auto-detect: if .ralph/specs/ exists and contains .md files, SDD mode activates automatically
3. Auto-generate: if no specs folder exists, ralph calls the agent once to split your task file into specs

Use --no-sdd to disable SDD and fall back to the flat task loop.

Using a specs folder directly

ralph --specs path/to/specs/

Auto-generating specs from a task file

ralph --file my-big-task.md
# ralph will generate .ralph/specs/001-*.md, 002-*.md, etc. then process them

The generate-specs subcommand

Generate specs without running the loop:

ralph --file my-task.md generate-specs

Spec file format

Each spec file should have these sections:

## Overview
Brief description of the feature or work unit.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Out of Scope
Items explicitly excluded from this spec.

## Notes
Additional context or implementation hints.

Spec completion

Each spec is considered complete when a sibling .done file exists (e.g., 001-feature.done for 001-feature.md). Use --force to re-run completed specs.

Choosing a model for spec generation

ralph --sdd-model gpt-5 --file tasks.md

How It Works

1. ralph reads a task description from a file or stdin
2. It creates an iteration directory to store the execution history
3. For each iteration:
   • ralph builds a prompt that includes the original task and the history of previous iterations
   • GitHub Copilot CLI processes the prompt and attempts to complete the task
   • The output is saved to a log file
   • If Copilot creates a .ralph/DONE file, the task is considered complete
4. The loop continues until the task is complete or the maximum number of iterations is reached

Development

Setup Development Environment

Install all required development tools:

make setup

This will install:

• Copilot CLI
• ShellCheck (shell script linter)

Development Commands

The project uses a Makefile for common development tasks:

View all available commands

make help

Code Quality

Check code for linting issues:

make check

Cleanup

Remove the .ralph directory:

make clean

Development Tools

• ShellCheck: Static analysis tool for shell scripts
• Makefile: Automation for common development tasks

Making Changes

1. Make your changes to src/ralph.bash
2. Run checks: make check
3. Test your changes locally
4. Submit a pull request

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Security

If you discover a security vulnerability, please see SECURITY.md for reporting instructions.

License

This project is licensed under the terms specified in the LICENSE file.

Acknowledgments

• Inspired by Geoffrey Huntley
• Loop approach adapted from this gist
• Powered by GitHub Copilot CLI