Chief Wiggum

░█▀▀░█░█░▀█▀░█▀▀░█▀▀░░░█░█░▀█▀░█▀▀░█▀▀░█░█░█▄█
░█░░░█▀█░░█░░█▀▀░█▀▀░░░█▄█░░█░░█░█░█░█░█░█░█░█
░▀▀▀░▀░▀░▀▀▀░▀▀▀░▀░░░░░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀

Autonomous coding agent CLI. Point it at a plan, watch it build.

Install

npx chiefwiggum@latest

That's it. Now you can use chiefwiggum anywhere.

Requires: Claude Code installed and authenticated.

Usage

Interactive Setup

cd your-project
chiefwiggum new

You'll be prompted with numbered options:

How would you like to set up this project?

  1) From a plan file - I have a plan.md ready
  2) Describe it - I'll tell you what to build
  3) Existing TODO - Just start the loop with current TODO.md

Enter choice [1-3]:

From a Plan File

chiefwiggum new plans/myplan.md

Generates specs and starts building.

Just Run the Loop

chiefwiggum loop
# or just
chiefwiggum

Works through existing TODO.md tasks.

Check Status

chiefwiggum status

Shows project status and task progress.

What It Does

1. Setup (chiefwiggum new)

   • Interactive Q&A or use existing plan
   • Generates: specs/prd.md, specs/technical.md, CLAUDE.md, TODO.md

2. Build Loop (chiefwiggum loop)

   • Picks first unchecked task from TODO.md
   • Spawns Claude to implement it
   • Commits changes
   • Repeats until done

3. Guardrails

   • 3 consecutive failures → stops
   • 5 cycles without commits → stops
   • 60 minute timeout per task

Project Structure

After setup:

your-project/
├── specs/
│   ├── prd.md           # Product requirements
│   └── technical.md     # Technical specification
├── CLAUDE.md            # Project context for AI
├── TODO.md              # Task list (checkbox format)
└── plans/
    └── plan.md          # Your original plan (if provided)

Configuration

Environment variables:

| Variable | Default | Description | |----------|---------|-------------| | TODO_FILE | TODO.md | Task list file | | ITERATION_TIMEOUT_MINUTES | 60 | Max time per task | | MAX_CONSECUTIVE_FAILURES | 3 | Failures before stopping | | MAX_NO_COMMIT_CYCLES | 5 | Cycles without progress | | COOLDOWN_SECONDS | 5 | Pause between tasks |

Requirements

• Claude Code CLI (authenticated)
• Git
• jq
• tmux (recommended for long builds)

Tips

• Run in tmux: For long builds, use tmux so you can detach
• Review specs first: After chiefwiggum new, review generated specs before starting loop
• Watch the output: Claude streams progress so you can see what it's doing
• Check commits: Each task should produce a commit - if not, something's wrong

Troubleshooting

Loop stops with "3 consecutive failures"

• Check /tmp/chiefwiggum-iter*.log for error details
• Fix the issue, then run chiefwiggum again

Loop stops with "No commits for 5 cycles"

• Tasks may be too vague or blocked
• Review TODO.md and make tasks more specific

jq: command not found

brew install jq        # macOS
sudo apt install jq    # Ubuntu

License

MIT