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 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."
bun install -g ralph-wiggum-cli
Or with npm:
npm install -g ralph-wiggum-cli
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
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).
.ralph-wiggum/specs/ describing what to buildralph-wiggum-cli plan — AI analyzes specs and breaks them into small, actionable tasks in implementation.jsonralph-wiggum-cli build — AI implements tasks one at a time, each with a reference to its parent spec<TASK_DONE>Why task-first?
# 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
claude CLI)amp CLI)droid CLI)opencode CLI)cursor CLI)codex CLI)gemini CLI)pi CLI)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 skippedThe loop also stops when:
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"
}
}
}
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer