ralph-wiggum

name	ralph-wiggum
description	Use the Ralph Wiggum CLI for autonomous AI coding loops. Use when running ralph commands, setting up autonomous coding workflows, or managing AI agent loops for planning and building features.

Ralph CLI

Ralph runs AI agents (Claude Code, Amp, Droid, OpenCode, Cursor, Codex, Gemini, Pi) in continuous loops until tasks are complete.

Task-first approach: Instead of giving agents autonomy to work through specs, Ralph decomposes specs into small tasks during planning, then feeds tasks to agents one at a time during building. Smaller tasks keep agents focused and out of the "dumb zone."

Installation

bun install -g ralph-wiggum-cli

Or with npm:

npm install -g ralph-wiggum-cli

Core Commands

ralph-wiggum-cli init                    # Initialize project (creates .ralph-wiggum/ directory)
ralph-wiggum-cli plan                    # Run planning mode - analyzes specs, creates implementation.json
ralph-wiggum-cli build                   # Run build mode - implements tasks one at a time
ralph-wiggum-cli stop                    # Stop running session
ralph-wiggum-cli status                  # Check current session status
ralph-wiggum-cli agents                  # List available AI agents and installation status

Project Structure

After ralph-wiggum-cli init, a .ralph-wiggum/ directory is created:

.ralph-wiggum/
├── config.json              # Project config (agents, notifications, sessions)
├── PROMPT_plan.md           # Instructions for planning mode (customizable)
├── GUARDRAILS.md            # Compliance rules (before/after checks)
├── PROGRESS.md              # Audit trail of completed work
├── implementation.json      # Structured task list (generated by plan mode)
├── specs/                   # Specification files you write
└── logs/                    # Session logs (gitignored)

Note: Build prompts are dynamically generated per task (no PROMPT_build.md file).

Workflow

1. Write specifications in .ralph-wiggum/specs/ describing what to build
2. Run ralph-wiggum-cli plan — AI analyzes specs and breaks them into small, actionable tasks in implementation.json
3. Run ralph-wiggum-cli build — AI implements tasks one at a time, each with a reference to its parent spec
4. Plan mode exits when AI outputs <TASK_DONE>
5. Build mode loops through tasks, marking each done/blocked/failed, until all complete

Why task-first?

• Smaller context = smarter agent (avoids the "dumb zone")
• Deterministic execution (you control task order via priority)
• Better progress tracking (each task is a checkpoint)

Command Options

# Init with different agents for plan vs build
ralph-wiggum-cli init -a <agent>              # Set agent for both modes
ralph-wiggum-cli init --plan-agent claude --build-agent droid
ralph-wiggum-cli init --plan-model opus --build-model sonnet
ralph-wiggum-cli init -f                      # Force reinitialization

# Plan/Build options
ralph-wiggum-cli plan -v                      # Verbose output (shows agent stdout/stderr)
ralph-wiggum-cli plan -a amp                  # Override agent for this session
ralph-wiggum-cli plan -m <model>              # Override model for this session

ralph-wiggum-cli build -v                     # Verbose output
ralph-wiggum-cli build -a droid               # Override agent for this session
ralph-wiggum-cli build -m <model>             # Override model for this session

Supported Agents

• claude: Claude Code (claude CLI)
• amp: Amp Code (amp CLI)
• droid: Factory Droid (droid CLI)
• opencode: OpenCode (opencode CLI)
• cursor: Cursor Agent (cursor CLI)
• codex: OpenAI Codex (codex CLI)
• gemini: Gemini CLI (gemini CLI)
• pi: Pi coding agent (pi CLI)

Completion Signals

Plan mode: Exits when AI outputs <TASK_DONE>

Build mode (task-level):

• <TASK_DONE> — task completed successfully, moves to next task
• <TASK_BLOCKED reason="..."> — task is blocked, logged and skipped

The loop also stops when:

• User presses Ctrl+C
• All tasks are completed

Notifications

Ralph supports Telegram notifications for loop events (start, task complete, blocked, done). Configure during init or in .ralph-wiggum/config.json:

{
  "notifications": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token",
      "chatId": "your-chat-id"
    }
  }
}