Project Overview
The Problem
AI coding agents hit a wall. After 50+ tool calls, context fills up with failed attempts. They repeat the same mistakes endlessly. There's no way to pass learnings between sessions.
Context windows are finite. Traditional approaches fill them with noise until the agent can no longer function effectively.
The Solution
Ralph implements Geoffrey Huntley's deliberate context rotation strategy. Each iteration starts with a fresh context window. Progress and learnings persist in files, not memory.
Guardrails (signs) accumulate lessons learned, preventing the same mistakes from being repeated across sessions.
Platform Support
macOS
Intel and Apple Silicon with GPU acceleration for local models via Metal.
- • Homebrew integration
- • Apple Silicon GPU support
- • iTerm2 / Terminal.app
Linux
Ubuntu, Debian, Fedora, Arch, and Raspberry Pi OS with apt/dnf/pacman support.
- • Raspberry Pi 4/5
- • Docker support
- • Systemd services
Windows
PowerShell and Batch scripts with winget package manager integration.
- • PowerShell 5.1+
- • Windows Terminal
- • VS Code integration
Key Features
Context Rotation
Each iteration starts fresh. State is read from files, not agent memory. This prevents context window pollution.
- • Fresh context each loop
- • File-based state persistence
- • Git-based progress tracking
Guardrails System
When agents fail, they write "signs" documenting what went wrong. Future iterations read these first, avoiding repeated mistakes.
- • Accumulated lessons
- • Failure prevention
- • Self-improving loops
10+ AI Agents
Switch between cloud APIs and local models seamlessly. Use what works best for your task and budget.
- • Gemini CLI (1M+ tokens, free)
- • Claude, OpenAI, Anthropic
- • Ollama, LM Studio (local)
Cloud/CI Deployment
Run on any server or integrate into CI/CD pipelines. Includes Docker, systemd, and pipeline configs.
- • AWS, GCP, Azure, DO
- • GitHub Actions, GitLab CI
- • Docker Compose ready
How It Works
RALPH LOOP
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────────┐ ┌─────────────┐
│ Read │ │ Execute │ │ Commit │
│ State │ ───► │ Agent │ ───► │ Progress │
│ Files │ │ Task │ │ to Git │
└─────────┘ └─────────────┘ └─────────────┘
│ │ │
│ .ralph/ │ │
│ ├── progress.md │ │
│ ├── guardrails.md │ If not done │
│ └── errors.log │ │ │
│ │ ▼ │
└─────────────────────────┴──────── ROTATE ◄───────┘
(Fresh Context)
Quick Start
# One-line install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/craigm26/Ralph/main/install.sh | bash
# Run with Gemini (free, 1M+ token context)
./ralph.sh
# Or with local Ollama
./ralph.sh ollama
# Define your task in RALPH_TASK.md
# Ralph works until all checkboxes are checkedUse Cases
Multi-Hour Refactors
Set it running overnight. Come back to a refactored codebase with every change committed and documented.
Test Coverage
"Write tests until coverage hits 80%" - Ralph iterates until the success criteria are met.
Documentation
"Document every public function" - tedious but well-defined tasks are perfect for autonomous execution.
Technical Stack
Supported Agents
Infrastructure
Project Stats
Cloud and local
macOS, Linux, Windows, Cloud
Open source
Active development
Credits
- Original Technique: Geoffrey Huntley - The Ralph Wiggum concept of deliberate context rotation
- Cursor Implementation: Agrim Singh - Early Cursor-based implementation
- Cross-Platform Port: This implementation extends the technique to support 10+ AI agents across all major platforms
Ready to Try Autonomous AI Development?
Get started with Ralph in minutes. Define your task, run the loop, check back when it's done.