Ralph CLI

A command-line tool for managing Ralph Wiggum AI development workflows across projects.

Based on the Ralph Wiggum Technique - an AI development methodology that uses autonomous coding loops with AI agents.

This implementation takes a task-first approach: instead of giving agents autonomy to work through specs, we decompose specs into small tasks during planning, then feed tasks to agents one at a time. Smaller tasks keep agents focused and out of the "dumb zone."

Meta: This CLI was built by pointing an AI agent at the Ralph Wiggum technique repo, then using Ralph itself to implement and refine the tool. Recursive AI development in action.

Installation

bun install -g ralph-wiggum-cli

Or with npm:

npm install -g ralph-wiggum-cli

For local development:

git clone <repo>
cd ralph-cli
bun install
bun link

AI Agent Skills

Ralph includes a skill file that teaches AI agents how to use the CLI.

Claude Code

cp -r .claude/skills/ralph ~/.claude/skills/

Quick Start

# Initialize Ralph in your project
cd your-project
ralph-wiggum-cli init

# Run planning mode (analyzes specs and creates implementation.json)
ralph-wiggum-cli plan

# Run build mode (executes tasks from implementation.json)
ralph-wiggum-cli build

# View status
ralph-wiggum-cli status

# Stop a running session
ralph-wiggum-cli stop

Commands

| Command | Description | | ------------------------- | ---------------------------------------------- | | ralph-wiggum-cli init | Initialize Ralph in the current project | | ralph-wiggum-cli plan | Run planning mode (analyze specs, create plan) | | ralph-wiggum-cli build | Run build mode (execute tasks from plan) | | ralph-wiggum-cli stop | Stop running session | | ralph-wiggum-cli status | Show project status and sessions | | ralph-wiggum-cli agents | List available AI agents |

Options

Init Options

ralph-wiggum-cli init [options]

  -a, --agent <agent>       AI agent for both modes (default: claude)
  -m, --model <model>       Model for both modes
  --plan-agent <agent>      AI agent for planning mode
  --plan-model <model>      Model for planning mode
  --build-agent <agent>     AI agent for building mode
  --build-model <model>     Model for building mode
  -f, --force               Force reinitialization

Plan/Build Options

ralph-wiggum-cli plan [options]
ralph-wiggum-cli build [options]

  -a, --agent <agent>  Override the configured agent
  -m, --model <model>  Override the configured model
  -v, --verbose        Enable verbose output (shows agent stdout/stderr)

Supported Agents

| Agent | Description | | ---------- | -------------------------------------------------------------------------- | | claude | Claude Code by Anthropic | | amp | Amp Code by Sourcegraph | | droid | Factory Droid CLI | | opencode | OpenCode CLI | | cursor | Cursor Agent CLI | | codex | OpenAI Codex CLI | | gemini | Gemini CLI by Google | | pi | Pi coding agent |

Project Structure

After ralph-wiggum-cli init, your project will have:

your-project/
└── .ralph-wiggum/
    ├── config.json          # Project config and session history
    ├── PROMPT_plan.md       # Planning mode prompt (customizable)
    ├── implementation.json  # Task tracking (generated by plan mode)
    ├── GUARDRAILS.md        # Compliance rules (before/after checks)
    ├── PROGRESS.md          # Audit trail of completed work
    ├── specs/               # Specification files
    │   └── example.md       # Example spec template
    └── logs/                # Session logs (gitignored)

How It Works

This CLI implements a task-first variation of the Ralph Wiggum technique.

Traditional Ralph implementations give agents autonomy to pick tasks and work spec-by-spec. This approach is different: we break specs into small, focused tasks during planning, then feed them to the agent one at a time during building.

Why task-first?

• Smaller context = smarter agent. Large specs push agents into the "dumb zone" where they lose focus and make mistakes. Small tasks keep them sharp.
• Deterministic execution. Tasks are picked by priority, not agent judgment. You control the order.
• Better progress tracking. Each task completion is a checkpoint. If something fails, you know exactly where.

Planning Phase (ralph-wiggum-cli plan)

1. AI reads all specs in .ralph-wiggum/specs/
2. Audits the codebase to understand current state
3. Breaks each spec into small, actionable tasks with acceptance criteria
4. Outputs implementation.json with prioritized task queue

The planner's job is to think deeply about the work and decompose it properly. This is where complexity lives.

Building Phase (ralph-wiggum-cli build)

1. Picks the next pending task (by spec priority, then task order)
2. Injects the task directly into the agent's context, along with a reference to the larger spec for background
3. Agent implements just that one task
4. On completion, marks task done and loops to the next
5. Continues until all tasks across all specs are complete

The builder's job is simple: execute one small task at a time. No decisions, no prioritization—just focused implementation.

Task Completion Markers

Agents signal completion via stdout:

• <TASK_DONE> - Task completed successfully
• <TASK_BLOCKED reason="..."> - Task blocked (missing dependency, unclear requirement)

Notifications

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

License

MIT