Run AI terminal tools in repeatable loops
`ailoop` helps you replace brittle one-off shell loops with a safer flow built around YAML config, pause/resume, strict task files, durable state, saved presets/history, and JSON-friendly output.
$ ailoop ps ID State Prog Updated Summary ------------- ------------ ----- ------------------- ------- demo-loop ▶ running 3/∞ 2026-05-16 08:00:11 review repo $ ailoop pause demo-loop ⏸ demo-loop · pause_requested
Better than a brittle while true shell loop
Most AI terminal workflows begin as a fast shell loop and then grow messy. `ailoop` keeps the good part — fast repetition — while adding controls, structure, state, and automation-friendly output.
🔁 Repeatable runs
Run forever or for a fixed number of steps with one command.
⚙️ YAML config
Keep defaults in one config file and override them per run.
💾 Durable state
Track loops on disk so pause, resume, status, and stats stay consistent.
🧠 Presets + history
Save reusable run setups locally, favorite them, and replay them into new loops.
⏸ Control flow
Pause or stop active loops without killing the whole tool session.
✅ Task file mode
Use a strict Markdown task file when the loop should stop only after the list is done.
🧾 JSON output
Use machine-friendly status, stats, logs, memory entries, and task-file checks in scripts.
Get to the first successful run fast
Two small steps are enough for the first run: install locally, then start one loop.
1. Install
uv sync
2. Run
ailoop init-config ailoop run "Review the repo and keep iterating." \ --runner opencode \ --agent orchestrator
Watch / control / inspect
ailoop ps ailoop tail <loop-id> ailoop pause <loop-id> ailoop resume <loop-id> ailoop status <loop-id>
Save + replay
ailoop memory save "Quick review" "Review the repo." \ --runner opencode --agent orchestrator ailoop memory list ailoop replay <memory-id>
Use a strict Markdown task file when the loop should stop on task completion
Task file mode is a strong fit for structured AI work. The loop continues while To do or Doing still has real tasks.
Valid file
# Loop Tasks ## To do - [ ] First task ## Doing - None ## Done - None
Use it
ailoop init-task-file ./loop_tasks.md ailoop check-task-file ./loop_tasks.md ailoop run "Work the task list." \ --task-file ./loop_tasks.md \ --until-tasks-complete
Fits the common loop shapes
Repo review
Keep iterating on one repo review or maintenance prompt until you stop it.
Bounded runs
Use fixed steps when you want exactly 3, 5, or 10 iterations and a clean stop.
Task lists
Run against a strict Markdown task file and stop when the list is complete.