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 TODO.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

Development

# Install dependencies
make sync

# Run tests
make test

# Clean stale build artifacts (dist/, dist.*, build/, *.egg-info)
make clean-build

# Build package
make build

# Publish to PyPI (expects PYPI_TOKEN in env, e.g. from ~/.zshrc.local)
make publish

How It Works

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

Commands

init

Initialize a new loop with LOOP-PROMPT.md, TODO.md, and .wiggum.toml.

wiggum init           # Interactive setup with Claude
wiggum init --force   # Overwrite existing files

run

Execute the agent loop until all tasks are complete.

wiggum run                    # Run with defaults
wiggum run -n 5               # Max 5 iterations
wiggum run --continue         # Keep context between iterations
wiggum run --keep-running     # Continue when tasks complete (agent can add new)
wiggum run --timeout 900      # Kill hung agent calls after 15 minutes
wiggum run --identify-tasks   # Analyze codebase, populate TODO.md, then exit
wiggum run --no-yolo          # Ask for permissions
wiggum run -v                 # Show git status after each iteration

add

Add tasks directly from the command line.

wiggum add "Fix the login bug"
wiggum add "Refactor auth module" -f my-tasks.md

list

Show all tasks grouped by status.

wiggum list

suggest

Use Claude to discover and suggest tasks interactively.

wiggum suggest       # Interactive prompts
wiggum suggest -y    # Accept all suggestions

spec

Create detailed spec files for complex features.

wiggum spec user-auth    # Creates specs/user-auth.md

Tasks can reference specs: - [ ] Implement auth (see specs/user-auth.md)

upgrade

Upgrade wiggum-managed files to the latest template versions.

wiggum upgrade            # Upgrade all files
wiggum upgrade prompt     # Only LOOP-PROMPT.md
wiggum upgrade config     # Only .wiggum.toml
wiggum upgrade --dry-run  # Preview changes

clean

Remove wiggum-managed files.

wiggum clean              # Interactive removal
wiggum clean --keep-tasks # Remove config, keep TODO.md
wiggum clean --all        # Remove everything

Configuration

Settings are stored in .wiggum.toml:

[security]
yolo = true           # Skip permission prompts (default: true)
allow_paths = ""      # Comma-separated paths to allow writing

[loop]
max_iterations = 10   # Default iteration limit
timeout = 1800        # Per-iteration agent timeout in seconds

[git]
enabled = false       # Enable git workflow
branch_prefix = "wiggum"  # Prefix for auto-generated branches

CLI flags override config file settings.

Git Workflow

Create branches and PRs automatically:

wiggum run --pr           # Create branch, run loop, open PR when done
wiggum run --pr --no-branch  # Use current branch, still create PR

The --pr flag:

1. Fetches and merges from main
2. Creates a new branch (e.g., wiggum/fix-auth-bug)
3. Runs the loop
4. Opens a PR when complete

Multi-Agent Support

wiggum supports multiple coding agents:

wiggum run --agent claude   # Claude Code (default)
wiggum run --agent codex    # OpenAI Codex CLI
wiggum run --agent gemini   # Google Gemini CLI

Learning Diary

wiggum automatically captures learnings during each session in .wiggum/session-diary.md. After the loop completes, it consolidates these into your CLAUDE.md for future sessions.

wiggum run --no-diary        # Disable diary for this run
wiggum run --no-consolidate  # Skip consolidation after run

License

MIT