wiggum

A minimal, opinionated tool for running agent loops.

while true; do cat PROMPT.md | claude --print; done

This is the "Ralph Wiggum loop" - the simplest possible agent loop. wiggum adds just enough guardrails to make it practical.

Philosophy

• Simple - prefer simplicity whenever possible
• Minimal - does one thing well: run a prompt in a loop until tasks are done
• Opinionated - sensible defaults, few options
• Unobtrusive - infer what you can, don't ask obvious questions
• Task-driven - stops when TASKS.md has no unchecked items
• Test-driven - write tests first for new behavior; skip tests for trivial changes (renames, constants, config)

Installation

# Run directly (no install needed)
uvx wiggum init

# Or install globally
uv tool install wiggum

# Upgrade to latest version
uv tool upgrade wiggum

Quick Start

# Set up (Claude helps plan your tasks)
wiggum init

# Run the loop
wiggum run

How It Works

1. init creates LOOP-PROMPT.md (workflow) and TASKS.md (task list)
2. run executes Claude with the prompt, checks TASKS.md after each iteration
3. Loop stops when all tasks are checked off (- [x])

Options

wiggum run                    # Run (skips permission prompts by default)
wiggum run --no-yolo          # Ask for permissions
wiggum run -n 5               # Max 5 iterations
wiggum run --continue         # Keep context between iterations
wiggum run --keep-running     # Continue even when tasks complete (agent can add new tasks)
wiggum run --identify-tasks   # Analyze codebase and add refactoring tasks to TASKS.md
wiggum run --agent codex      # Use a different agent (codex, gemini, etc.)

License

MIT