Ralph Wiggum

"Me fail English? That's unpossible!" - Ralph Wiggum

An autonomous agent loop toolkit for Claude Code and Codex. Ralph iteratively picks tasks from an implementation plan, implements them, validates with configurable backpressure, commits, and continues without human intervention.

Based on The Ralph Playbook

Features

• Autonomous Execution: Run implementation loops without manual intervention
• Multi-CLI Support: Works with Claude Code and OpenAI Codex
• Docker Sandboxing: Safe execution environment for autonomous runs
• Project Agnostic: Works with any tech stack
• Configurable Prompts: Customize planning and building behavior

Quick Start

Installation

# Clone the repository
git clone https://github.com/flowglad/ralph.git ~/.ralph

# Run the installer
~/.ralph/install.sh

# Reload your shell
source ~/.bashrc  # or ~/.zshrc

Initialize a Project

cd ~/my-project
ralph init

This creates:

• ralph.config - Project configuration
• ralph/AGENTS.md - Project operations guide
• ralph/plan.md - Implementation plan (human-readable, you edit this)
• ralph/prd.json - Task state tracking (machine-readable, Ralph manages this)
• ralph/specs/ - Feature specifications
• ralph/PROMPT_*.md - Agent prompts

Run Ralph

# Planning mode - analyze specs and create implementation plan
ralph plan

# Build mode - implement tasks from the plan
ralph

# Build with iteration limit
ralph 20

# Scoped planning for specific work
ralph plan-work "user authentication"

Using an Existing Plan

If you already have an implementation plan in markdown, import it directly:

# 1. Initialize Ralph (if not already done)
ralph init

# 2. Import your markdown plan
ralph import ~/my-plan.md

# 3. Run planning to sync markdown to JSON tracking
ralph plan

# 4. Start building
ralph

Your markdown plan can use any format - Ralph will read it and create JSON tasks:

# Implementation Plan

## Goal
Build user authentication system

## Tasks

### Pending
1. **Set up database schema** - Create users table with auth fields
   - Related spec: `specs/auth.md`

2. **Implement registration** - POST /api/auth/register endpoint
   - Depends on: database schema

3. **Add login/logout** - JWT-based session management

### Completed
- [x] Project setup

How it works:

• ralph/plan.md - You write requirements here (human-friendly markdown)
• ralph/prd.json - Ralph tracks state here (machine-readable JSON)

Ralph keeps both in sync: reads requirements from plan.md, tracks completion status in prd.json. You can edit plan.md while Ralph runs to adjust priorities.

Docker Mode (Recommended)

For autonomous runs with --dangerously-skip-permissions, use Docker for safety:

ralph --docker plan
ralph --docker 20

CLI Reference

ralph                       Build mode, unlimited iterations
ralph <n>                   Build mode, max n iterations
ralph plan                  Planning mode
ralph plan <n>              Planning mode, max n iterations
ralph plan-work "<scope>"   Scoped planning for specific work
ralph import <plan.md>      Import existing markdown plan
ralph status                Show current task status
ralph clean                 Remove completed tasks from tracking
ralph init                  Initialize Ralph in current project
ralph help                  Show help

Options:
  --docker                  Run in Docker sandbox

How It Works

The Loop

1. Read: Agent reads specs, plan.md (requirements), and prd.json (state)
2. Choose: Agent selects the highest priority pending task (respecting dependencies)
3. Implement: Agent writes code to complete the task per plan.md
4. Validate: Agent runs tests, typecheck, lint
5. Update: Agent marks task complete in both prd.json (state) and plan.md (moves to Completed)
6. Commit: Agent commits changes with descriptive message
7. Push: Loop pushes to remote and continues

Two-File System

File	Purpose	Who Edits
ralph/plan.md	Requirements in human-readable markdown	You + Ralph
ralph/prd.json	State tracking (status, timestamps)	Ralph only

This separation means:

• You write plans in familiar markdown
• Ralph tracks machine state in JSON
• Both stay in sync automatically

Planning Mode

In planning mode, Ralph analyzes your specs and updates both plan.md and prd.json without making code changes. Use this to:

• Generate initial task list from specs
• Sync markdown plan to JSON tracking
• Discover gaps in specifications

Building Mode

In building mode, Ralph picks tasks from prd.json, reads details from plan.md, implements, validates, and commits. The loop continues until:

• All tasks are complete
• Max iterations reached
• Agent encounters an unrecoverable error

Configuration

ralph.config

# CLI: claude or codex
RALPH_CLI="claude"

# Model to use
RALPH_MODEL="opus"

# Ralph directory location
RALPH_DIR="ralph"

# Custom goal for planning
RALPH_GOAL="Implement all specs"

# Additional CLI flags
RALPH_CLAUDE_FLAGS=""
RALPH_CODEX_FLAGS=""

# Debug mode
RALPH_DEBUG="false"

AGENTS.md

Your project's operations guide. Document:

• How to build and run the project
• Validation commands (test, typecheck, lint)
• Codebase patterns to follow
• Tech stack information

Ralph updates this file with learnings during execution.

Specs

Create specifications in ralph/specs/:

# Feature Name

## Job to Be Done
What user need does this address?

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

## Technical Notes
Implementation guidance (optional)

Examples

See the examples/ directory for stack-specific configurations:

• examples/node-typescript/ - Node.js with TypeScript
• examples/python/ - Python with pytest/mypy
• examples/rust/ - Rust with Cargo

Documentation

• Philosophy - Design principles behind Ralph
• Docker Guide - Sandboxed execution setup
• Advanced Usage - Power user patterns
• Troubleshooting - Common issues
• Comparison - Ralph vs alternatives

Safety Considerations

Ralph runs with --dangerously-skip-permissions to enable autonomous execution. This means the agent can:

• Read and write any file
• Execute any command
• Make network requests

Recommendations:

1. Always use Docker mode (--docker) for autonomous runs
2. Review changes before pushing to main branches
3. Set up branch protection rules
4. Monitor agent output for unexpected behavior
5. Use resource limits in Docker

Requirements

• Bash 4.0+
• Git
• jq (for ralph status and ralph clean)
• Claude Code CLI (npm i -g @anthropic-ai/claude-code) or
• Codex CLI (npm i -g @openai/codex)
• Docker (optional, for sandboxed execution)

Uninstallation

~/.ralph-wiggum/uninstall.sh
rm -rf ~/.ralph-wiggum

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines before submitting PRs.