ailoop 🔁

Run AI terminal tools in repeatable loops

YAML config, durable state, task-file mode, presets/history, pause/resume, and stats for OpenCode, Codex, Claude, and more.

Docs: GitHub Pages · docs/index.md

By: Diego Marinho · LinkedIn

Support: https://buy.stripe.com/8x200i8bSgVe3Vl3g8bfO00

ailoop is a small CLI for repeatable AI terminal loops with durable state, task-file mode, pause/resume controls, and machine-friendly output.

It is built for people who want a simple way to run AI terminal tools like OpenCode, Codex, and Claude Code in safe repeatable loops instead of brittle one-off shell snippets.

Why ailoop? 🧭

Most AI terminal workflows start as a quick while true loop, then grow messy fast.

ailoop gives you:

• ✅ repeatable loop runs
• ✅ YAML config + CLI overrides
• ✅ durable local state
• ✅ pause / resume / stop controls
• ✅ strict Markdown task-file mode
• ✅ saved presets + replayable history
• ✅ workspace-aware TUI follow-ups + prompt history
• ✅ stats, logs, and tail commands
• ✅ JSON output for automation

Quick start ⚡

Install:

uv sync

Run from this repo:

uv run ailoop init-config
uv run ailoop run "Do exactly 3 iterations." --steps 3

Or download the wheel from the latest GitHub release, then install it:

pipx install ./ai_loop-*-py3-none-any.whl
ailoop --help

Start:

ailoop init-config
ailoop run "Review the repo and iterate for 3 steps." --runner opencode --agent orchestrator --steps 3
ailoop run "Work this repo." --workspace-root . --steps 3
ailoop run "Do exactly 5 iterations." --steps 5

Task file mode:

ailoop init-task-file ./loop_tasks.md
ailoop check-task-file ./loop_tasks.md
ailoop run "Work the task list." --runner opencode --agent orchestrator --task-file ./loop_tasks.md --until-tasks-complete

Watch:

ailoop ps
ailoop list --active
ailoop tail <loop-id>
ailoop --json ps

Control:

ailoop pause <loop-id>
ailoop resume <loop-id>
ailoop stop <loop-id>

Inspect:

ailoop status <loop-id>
ailoop stats <loop-id>
ailoop logs <loop-id>
ailoop --json status <loop-id>

Presets + replay:

ailoop memory save "Quick review" "Review the repo." --runner opencode --agent orchestrator
ailoop memory list
ailoop memory show <memory-id>
ailoop replay <memory-id>

Task file mode ✅

Generate a valid task file:

ailoop task-template
ailoop task-template --with-rules
ailoop init-task-file ./loop_tasks.md
ailoop check-task-file ./loop_tasks.md
ailoop --json check-task-file ./loop_tasks.md

Format:

# Loop Tasks

## To do
- [ ] First task

## Doing
- None

## Done
- None

Rules:

• use only To do, Doing, Done
• To do: only - [ ] task or - None
• Doing: only - [ ] task or - None
• Done: only - [x] task or - None
• keep max 1 task in Doing
• move task To do -> Doing when start
• move task Doing -> Done and mark [x] when done

Exit codes:

• 0: valid and done
• 10: valid but still open (--state-exit-code)
• 1: invalid file

Commands 🧰

Core:

ailoop run "Prompt"
ailoop resume <loop-id>
ailoop pause <loop-id>
ailoop stop <loop-id>
ailoop replay <memory-id>

Memory:

ailoop memory save "Title" "Prompt"
ailoop memory save "Recent run" "Prompt" --kind history
ailoop memory list --kind preset
ailoop memory show <memory-id>
ailoop memory edit <memory-id> --title "New title"
ailoop memory favorite <memory-id>
ailoop memory delete <memory-id>

Watch + inspect:

ailoop ps
ailoop tui
ailoop tui --tmux
ailoop list --active
ailoop status <loop-id>
ailoop stats <loop-id>
ailoop logs <loop-id>
ailoop tail <loop-id>

TUI follow-up workflow:

• set Root directory to the repo/workspace you want to run
• type the base prompt in AI LOOP CONFIG and start or continue the loop
• press Ctrl+L to search persisted loop IDs, states, modes, runners, agents, prompts, workspaces, and task files
• press Enter to open a search result; Esc clears the focused loop search
• combine search with g running, a active, or l all without changing the selected loop or unsaved form edits
• type a one-shot instruction in Follow-up for next iteration and queue it with the button or Ctrl+Enter
• use Shift+N for one unchanged next iteration and Ctrl+J / Ctrl+K to switch loops
• Ctrl+J / Ctrl+K leave an editor on the first press, then switch visible loops without changing editor text
• the 6 history panel now shows recent workspace prompt/follow-up/result history plus loop iteration history

TUI memory smoke:

bash ./scripts/tui_memory_smoke.sh
tmux attach -t ailoop-tui-smoke

Task files:

ailoop init-task-file ./loop_tasks.md
ailoop check-task-file ./loop_tasks.md
ailoop check-task-file ./loop_tasks.md --state-exit-code

JSON + output modes:

ailoop --json ps
ailoop --json status <loop-id>
ailoop --json logs <loop-id>
ailoop --quiet check-task-file ./loop_tasks.md
ailoop --verbose check-task-file ./loop_tasks.md
ailoop --color always status <loop-id>

Config ⚙️

Default config path:

~/.config/ailoop/config.yaml

Example:

default_runner: opencode
default_agent: orchestrator

paths:
  agent_file: ~/Codes/Projects/agents_md/AGENTS.md
  state_dir: ~/.config/ailoop/state

prompt:
  pre_prompt_enabled: true
  attach_agent_file: true
  pre_prompt: |
    Work in small validated slices.
    Review current context before starting new work.
    Leave concise progress, blockers, and next action at the end.

loop:
  steps: null
  pause_seconds: 30
  continue_on_error: true
  retry_count: 0

runners:
  opencode:
    command: opencode
    args: ["run", "--agent", "{agent}", "{prompt}"]
  codex:
    command: codex
    args: ["{prompt}"]
  claude:
    command: claude
    args: ["{prompt}"]

Prompt assembly ✍️

Each iteration prompt is assembled in this order:

1. pre-prompt if enabled
2. agent file contents if enabled
3. user prompt
4. loop context block with iteration and previous result summary

Prompt and run logs are stored under the loop log directory for inspection.

Docs 📚

• docs hub
• GitHub Pages site
• config guide
• task-file mode
• examples
• runners
• hero banner brief

Support 💛

If ailoop saves you time, you can support ongoing maintenance and future releases here:

• Stripe: https://buy.stripe.com/8x200i8bSgVe3Vl3g8bfO00

By Diego Marinho:

• GitHub: Diego Marinho
• LinkedIn: Diego Marinho

More: docs/support.md

License 📝

MIT