Ralph CLI

# Ralph CLI

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

Based on the [Ralph Wiggum Technique](https://github.com/ghuntley/how-to-ralph-wiggum) - 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](https://github.com/ghuntley/how-to-ralph-wiggum), then using Ralph itself to implement and refine the tool. Recursive AI development in action.

## Installation

```bash
bun install -g ralph-wiggum-cli
```

Or with npm:

```bash
npm install -g ralph-wiggum-cli
```

For local development:

```bash
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

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

## Quick Start

```bash
# 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

```bash
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

```bash
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](https://docs.anthropic.com/en/docs/claude-code) by Anthropic |
| `amp`      | [Amp Code](https://ampcode.com) by Sourcegraph                             |
| `droid`    | [Factory Droid](https://factory.ai) CLI                                    |
| `opencode` | [OpenCode](https://opencode.ai) CLI                                        |
| `cursor`   | [Cursor Agent](https://cursor.com) CLI                                     |
| `codex`    | [OpenAI Codex](https://openai.com/codex) CLI                               |
| `gemini`   | [Gemini CLI](https://ai.google.dev/gemini-api) by Google                   |
| `pi`       | [Pi](https://github.com/mariozechner/pi-coding-agent) 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 executio

... (truncated)