Ralph: Cross-Platform Autonomous AI Development, Now Open Source

I’ve been using the Ralph Loop for a week now. It’s how I built Civqo in 7 nights. Today I’m open-sourcing my cross-platform implementation with support for every major platform and 10+ AI agents.

Repository: github.com/craigm26/Ralph

Platform Support

Platform	Status
Windows	✅ Supported
macOS (Intel & Apple Silicon)	✅ Supported
Ubuntu / Debian	✅ Supported
Raspberry Pi OS	✅ Supported
Cloud / VPS (AWS, GCP, etc.)	✅ Supported

Yes, it runs on a Raspberry Pi. And yes, Apple Silicon Macs get GPU acceleration for local models.

The Problem

AI coding agents hit a wall. After 50+ tool calls, context fills up with failed attempts. They repeat the same mistakes. There’s no way to pass learnings between sessions.

Geoffrey Huntley’s insight: accept that context is finite and design around it.

The Solution

Ralph implements deliberate context rotation:

┌─────────┐       ┌─────────────┐       ┌─────────────┐
│  Read   │  ──►  │   Execute   │  ──►  │   Commit    │
│  State  │       │    Agent    │       │  Progress   │
│  Files  │       │    Task     │       │   to Git    │
└─────────┘       └─────────────┘       └─────────────┘
     │                                         │
     │            If not done                  │
     └─────────── ROTATE (Fresh Context) ◄────┘

Each iteration starts clean. Progress persists in files, not memory. Learnings become “guardrails” that survive context resets.

10+ Agents

The original Ralph works with Claude Code. I needed cross-platform support and more options:

Agent	Type	Best For	Context
Gemini CLI	Cloud	Large projects, free tier	1M+ tokens
OpenAI	Cloud	GPT-4o, o1 reasoning	128K tokens
Anthropic	Cloud	Claude models	200K tokens
Ollama	Local	Privacy, offline	32K+ tokens
LM Studio	Local	GUI, easy switching	32K+ tokens
Network	Custom	Self-hosted deployments	Varies

Privacy-conscious? Run DeepSeek Coder locally with Ollama. Nothing leaves your machine.

Cost-conscious? Gemini CLI has a massive free tier with 1M+ token context.

Quick Start

macOS

# One-line install
curl -fsSL https://raw.githubusercontent.com/craigm26/Ralph/main/install.sh | bash

# With Ollama (runs on GPU with Apple Silicon!)
brew install ollama && ollama serve &
ollama pull codellama:13b
./ralph.sh ollama

Linux / Raspberry Pi

# One-line install
curl -fsSL https://raw.githubusercontent.com/craigm26/Ralph/main/install.sh | bash

# With Gemini (free)
npm install -g @google/gemini-cli && gemini auth login
./ralph.sh

Windows

git clone https://github.com/craigm26/Ralph.git
cd Ralph

# Gemini (free)
npm install -g @google/gemini-cli
gemini auth login
.\ralph.bat

Cloud / CI/CD

# Deploy to any server
curl -fsSL https://raw.githubusercontent.com/craigm26/Ralph/main/install.sh | bash -s -- --agent gemini

# Works with GitHub Actions, GitLab CI, Jenkins

Define your task in RALPH_TASK.md:

---
task: Build REST API
test_command: npm test
---

# Task: REST API

## Success Criteria
1. [ ] GET /health returns 200
2. [ ] POST /users creates user
3. [ ] All tests pass

Ralph works until all checkboxes are checked.

Guardrails (Signs)

The magic is in .ralph/guardrails.md. When an agent fails the same way twice, it writes a “sign”:

### Sign: Don't overwrite existing tests
- **Trigger**: When adding new tests
- **Instruction**: Append to test file, don't replace
- **Added after**: Iteration 3 - Accidentally deleted existing tests

Future iterations read this first. They don’t repeat the mistake.

It’s evolution through filesystem persistence.

Platform-Specific Tips

Apple Silicon Macs

Ollama runs models on the Metal GPU. A MacBook with 16GB RAM can run codellama:13b at excellent speeds. No cloud APIs needed.

Raspberry Pi

Use smaller models (phi:latest, codellama:7b) or cloud APIs like Gemini. A Pi 5 with 8GB RAM handles codellama:7b reasonably well.

Headless Servers

Ralph includes systemd service configs, Docker Compose files, and CI/CD pipeline examples. Run it overnight on a $5/month VPS.

Why This Works

Fresh context each loop - No accumulated confusion from failed attempts
Git as memory - Every iteration commits progress
Guardrails compound - Each failure makes future runs smarter
Agent-agnostic - Switch between cloud and local as needed

What I Use It For

Multi-hour refactors - Set it running, check in the morning
Migration tasks - Tedious but well-defined, perfect for Ralph
Test writing - “Write tests until coverage hits 80%”
Documentation - “Document every public function”

The key: tasks with clear success criteria. If you can’t define “done”, Ralph can’t either.

Credits

Geoffrey Huntley - Original technique
Agrim Singh - Cursor implementation
Boris Cherny - Claude Code, which Ralph extends

Get Started

Repository: github.com/craigm26/Ralph

MIT licensed. Contributions welcome.

The name Ralph comes from Ralph Wiggum. Dumb but persistent. Sometimes that’s exactly what you need.