Start it. Read the diff when it's done.

Wiggum wraps Claude Code in a loop that plans a change, implements it one task at a time, runs your project's own verify commands, fixes what fails, and commits as it goes. You start it from the shell and read the diff when it's done.

docs/csv-export_plan.md

- [ ] Add a CSV serializer for report rows

- [ ] Stream the export instead of buffering

- [ ] Wire the download button to the endpoint

- [ ] Cover empty and 10k-row reports

git log --oneline

4e91c2a serialize report rows as CSV

b7d0f18 stream the export rather than buffering it

1a5c86e wire the download button to the export endpoint

93fb204 cover empty and large report exports

c02e7dd summarize the CSV export run

$ wiggum plan issues/csv-export.md && wiggum execute docs/csv-export_plan.md

Two commands. Read the plan in between and edit it — it's just markdown checkboxes. Or run wiggum explain on it: what it is worth, and which decisions it leaves open.

What a run actually does

Four phases, in order. Wiggum prints them as it goes, so you can read a run's log and know where it stopped.

Phase 1

Diagnostic & status sync

Reads the repository against the plan and ticks off anything already done. Re-running a plan is cheap because this phase reconciles it first.

Phase 2

Implement, verify, fix

One task per iteration. After each, your verify commands run in order; a failure goes back to Claude with the error output until it passes or the retry budget runs out. Then it commits.

↺ repeats until the boxes are ticked, the run stalls, or it hits max_iterations

Phase 3

Summary & alignment

Reconciles the plan against what was built, writes a summary of what landed, what was deferred, and why the run stopped.

Phase 4

Documentation update

Optional. Pass --update-docs and it revises the files you name against what changed.

It verifies with your tools, not its own opinion

Wiggum has no idea whether your code is correct. It runs the commands you already trust and reads their exit codes.

.wiggumrc

# wiggum's own config, verifying wiggum
verify = shellcheck -s bash lib/wiggum.sh
verify = bats test/wiggum.bats
autofix = shfmt -w .

max_iterations = 30
max_validation_retries = 5

# sonnet plans and implements; save opus for harder work
model_plan = sonnet
model_execute = sonnet

A waterfall, not a checklist

Steps run in the order you write them and stop at the first failure, so a type error never costs you a full test run.

Autofix runs first

An autofix step gets one chance to correct itself before Claude is asked to look at it. Formatters fix formatting; Claude fixes logic.

Retries are capped

A step that can't be fixed stops the run instead of burning tokens against it. wiggum check runs the same waterfall on demand.

Model per phase

model_plan and model_execute pick the model separately — Sonnet is enough for most plans and implementation, so Opus is opt-in, not default.

Start it, walk away, keep watch

Runs last hours. wiggum top lists every run on the machine, whichever project it was started from, blocked and running first. The activity column tells a long task from a wedged one; RSS and CPU cover the run's whole process tree, because the cost is the claude it spawned rather than the pid in the row. The footer is the launch decision: load against cores, and swap.

wiggum watch is the other half: it blocks until a run finishes, attaches near the end of the backlog rather than replaying hours of it, names the task the plan is on, prints a [watch] line after a minute of silence so a quiet run never reads as a wedged one, and never exits 0 having waited for nothing — 0 means the run finished, 6 means your timeout ran out and the run is still going.

$ wiggum top

PLAN                                     PID      STATE                ACTIVITY  RSS      CPU    TASKS
docs/onboarding_plan.md                  621      running (blocked)    41m 12s   288.4M   0.2%   2/7 done, 5 left
/Users/me/api/docs/rate-limit_plan.md    8123     running              12s       1.2G     94.0%  3/9 done, 6 left
docs/csv-export_plan.md                  519      running              1m 4s     497.1M   89.4%  4/12 done, 8 left
docs/auth-hardening_plan.md              -        finished: complete   3d 2h     -        -      9/9 done

load 6.1 / 4 cores · swap 2.6G of 4.0G (65%) · 3 runs active

wiggum execute <plan> -bRun detached and get the shell back.

wiggum watch <plan>Stream a run's output and block until it finishes. A plan whose turn in a chain hasn't come is waited for, not reported missing.

wiggum watch --chainFollow a run across plans. Name it by plan file or pid; with neither, the only live run — or the only one in this directory.

wiggum kill <plan>Stop that run's process tree, and nothing else.

wiggum chain <a> <b> <c>Run plans back to back, stopping at the first failure.

wiggum chain --queue <file>Take the plan list from a file, re-read after each one, so you can append while it runs.

wiggum chain <a> <b> -bDetach the chain as one process; the plans still run in order.

wiggum top --jsonThe same rows as JSON, for a script that has to decide rather than read.

wiggum execute <plan> --at 01:07Start it tonight. No cron, no wake lock.

Install

One command. It copies the library, symlinks the CLI, and installs the /wiggum skill for Claude Code.

$ curl -fsSL https://raw.githubusercontent.com/benman1/wiggum/main/get.sh | bash

Then wiggum init in any project to generate a .wiggumrc from what it finds there — or wiggum init --yes from a setup script, which takes every overwrite without asking.

- [x] Claude Code CLI, installed and authenticated
- [x] Bash 4 or newer
- [x] A git repository to work in