Spec-driven queue
Prioritized markdown specs with explicit exclusions keep the agent from wandering.
How it works
From spec to commit, unattended.
01
Describe your goal
Start with a vague goal. owloop spec reads your codebase, asks clarifying questions, and drafts a concrete spec.
02
Review the spec
Edit the generated spec: requirements, shell-verifiable acceptance criteria, exclusions, and stuck behavior.
03
Start the loop
owloop run opens a full-screen TUI with an animated owl, iteration counter, token budget, and real-time status.
04
Verify & commit
The agent runs the exact shell commands from your acceptance criteria. Only green means commit.
05
Review in the morning
Open the worktree diff and the HTML report. Merge when ready. Go back to sleep.
A night with owloop
Leave work with specs. Come back to commits.
17:00
Describe the goal
Type a vague goal in plain English. The agent studies the codebase, asks 1–3 clarifying questions, and drafts a spec.
owloop spec "refactor error handling"
17:30
Review & queue specs
Edit the generated spec if needed, then queue it. Add more specs for the backlog.
owloop run --max-tokens 200000 --max-duration 480
22:00
Animated TUI loop
The full-screen TUI shows Ollie working: current spec, iteration count, token usage, and what the agent is doing — not raw command scrollback.
03:00
Commit only on green
Green acceptance criteria → commit + push. Failure → retry with exponential backoff. Same files flapping → fix-loop warning.
09:00
Review & merge
Open the HTML report, inspect the worktree diff, run your own sanity checks, then merge. Your main branch stayed clean all night.
Quality you can verify
No trust required. Only green checks count.
Shell-verified acceptance
The spec defines the exact commands that must pass. The agent does not decide for itself whether it is done.
Worktree isolation
Everything happens in a disposable git worktree. Your main checkout is never touched until you choose to merge.
Fix-loop detection
If the same files keep changing without the spec closing, the loop warns instead of burning tokens forever.
Budget caps & run notes
--max-tokens and --max-duration stop the run before costs spiral. Cross-iteration notes prevent the agent from repeating the same mistake.
Morning report
3
specs completed
14
commits
0
failures
12.4k
tokens used
Why owloop
Built for reliable overnight progress.
Fresh context per iteration
Each task starts clean. No accumulated context drift, no accidental side effects.
Git worktree isolation
Main checkout stays untouched until you review and merge the worktree branch.
Deterministic completion
Completion is a grep-able <promise>DONE</promise>, not a model guess.
Fix-loop detection
Catches death spirals when the same files are edited repeatedly without progress.
Token budget cap
Set --max-tokens and --max-duration. The loop stops before your wallet does.
Compared to
Pick the right loop for the job.
| owloop | /goal |
gnhf | |
|---|---|---|---|
| Completion check | grep <promise> |
Haiku judgment | grep |
| Best for | Backlog of verifiable tasks | One focused task, user present | Multi-agent overnight |
| Spec format | Constraint-oriented | Free-form | Free-form |
| Context | Fresh per iteration | Same session | Fresh per iteration |
| Isolation | Worktree | None | None |
Put your backlog to work overnight.
Install owloop, write your first spec, and let Ollie handle the rest.