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
bash
1bun install -g ralph-wiggum-cli
Or with npm:
bash
1npm install -g ralph-wiggum-cli
Core Commands
bash
1ralph-wiggum-cli init # Initialize project (creates .ralph-wiggum/ directory)
2ralph-wiggum-cli plan # Run planning mode - analyzes specs, creates implementation.json
3ralph-wiggum-cli build # Run build mode - implements tasks one at a time
4ralph-wiggum-cli stop # Stop running session
5ralph-wiggum-cli status # Check current session status
6ralph-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
- Write specifications in
.ralph-wiggum/specs/ describing what to build
- Run
ralph-wiggum-cli plan — AI analyzes specs and breaks them into small, actionable tasks in implementation.json
- Run
ralph-wiggum-cli build — AI implements tasks one at a time, each with a reference to its parent spec
- Plan mode exits when AI outputs
<TASK_DONE>
- 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
bash
1# Init with different agents for plan vs build
2ralph-wiggum-cli init -a <agent> # Set agent for both modes
3ralph-wiggum-cli init --plan-agent claude --build-agent droid
4ralph-wiggum-cli init --plan-model opus --build-model sonnet
5ralph-wiggum-cli init -f # Force reinitialization
6
7# Plan/Build options
8ralph-wiggum-cli plan -v # Verbose output (shows agent stdout/stderr)
9ralph-wiggum-cli plan -a amp # Override agent for this session
10ralph-wiggum-cli plan -m <model> # Override model for this session
11
12ralph-wiggum-cli build -v # Verbose output
13ralph-wiggum-cli build -a droid # Override agent for this session
14ralph-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:
json
1{
2 "notifications": {
3 "telegram": {
4 "enabled": true,
5 "botToken": "your-bot-token",
6 "chatId": "your-chat-id"
7 }
8 }
9}
