{"id":50773883,"url":"https://github.com/dmoliveira/ailoop","last_synced_at":"2026-06-11T21:36:37.438Z","repository":{"id":358143280,"uuid":"1240183096","full_name":"dmoliveira/ailoop","owner":"dmoliveira","description":"Repeatable AI terminal loops with YAML config, durable state, task-file mode, pause/resume controls, and JSON-friendly output.","archived":false,"fork":false,"pushed_at":"2026-05-25T21:23:32.000Z","size":217,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T21:35:47.230Z","etag":null,"topics":["agentic-workflows","ai","automation","cli","developer-tools","llm","python","task-runner","terminal","yaml"],"latest_commit_sha":null,"homepage":"https://dmoliveira.github.io/ailoop/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmoliveira.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/support.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T21:18:24.000Z","updated_at":"2026-05-19T23:01:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dmoliveira/ailoop","commit_stats":null,"previous_names":["dmoliveira/ailoop"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dmoliveira/ailoop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmoliveira%2Failoop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmoliveira%2Failoop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmoliveira%2Failoop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmoliveira%2Failoop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmoliveira","download_url":"https://codeload.github.com/dmoliveira/ailoop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmoliveira%2Failoop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34219510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflows","ai","automation","cli","developer-tools","llm","python","task-runner","terminal","yaml"],"created_at":"2026-06-11T21:36:36.692Z","updated_at":"2026-06-11T21:36:37.430Z","avatar_url":"https://github.com/dmoliveira.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ailoop 🔁\n\n[![PyPI](https://img.shields.io/pypi/v/ailoop?label=PyPI)](https://pypi.org/project/ailoop/)\n[![Python](https://img.shields.io/pypi/pyversions/ailoop)](https://pypi.org/project/ailoop/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#quick-start)\n[![Lint](https://img.shields.io/badge/lint-ruff-blue)](#quick-start)\n[![CLI](https://img.shields.io/badge/type-CLI-orange)](#quick-start)\n[![AI Loop Runner](https://img.shields.io/badge/focus-AI%20loop%20runner-8a2be2)](#why-ailoop-)\n[![Task File Mode](https://img.shields.io/badge/task%20file-strict%20markdown-0a7ea4)](#task-file-mode-)\n[![Docs](https://img.shields.io/badge/docs-in_repo-1f6feb)](docs/index.md)\n[![Site](https://img.shields.io/badge/site-github_pages-2ea44f)](https://dmoliveira.github.io/ailoop/)\n[![Support](https://img.shields.io/badge/support-Stripe-635bff)](docs/support.md)\n[![Diego Marinho](https://img.shields.io/badge/author-Diego%20Marinho-24292f)](https://github.com/dmoliveira)\n\n![ailoop hero](docs/branding/hero-banner.svg)\n\n\u003e ## Run AI terminal tools in repeatable loops\n\u003e\n\u003e YAML config, durable state, task-file mode, presets/history, pause/resume, and stats for OpenCode, Codex, Claude, and more.\n\u003e\n\u003e Docs: [GitHub Pages](https://dmoliveira.github.io/ailoop/) · [docs/index.md](docs/index.md)\n\u003e\n\u003e By: [Diego Marinho](https://github.com/dmoliveira) · [LinkedIn](https://www.linkedin.com/in/dmoliveira/)\n\u003e\n\u003e Support: https://buy.stripe.com/8x200i8bSgVe3Vl3g8bfO00\n\n`ailoop` is a small CLI for repeatable AI terminal loops with durable state, task-file mode, pause/resume controls, and machine-friendly output.\n\nIt 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.\n\n## Why ailoop? 🧭\n\nMost AI terminal workflows start as a quick `while true` loop, then grow messy fast.\n\n`ailoop` gives you:\n\n- ✅ repeatable loop runs\n- ✅ YAML config + CLI overrides\n- ✅ durable local state\n- ✅ pause / resume / stop controls\n- ✅ strict Markdown task-file mode\n- ✅ saved presets + replayable history\n- ✅ stats, logs, and tail commands\n- ✅ JSON output for automation\n\n## Quick start ⚡\n\nInstall:\n\n```bash\nuv sync\n```\n\nStart:\n\n```bash\nailoop init-config\nailoop run \"Review the repo and keep iterating.\" --runner opencode --agent orchestrator\nailoop run \"Do exactly 5 iterations.\" --steps 5\n```\n\nTask file mode:\n\n```bash\nailoop init-task-file ./loop_tasks.md\nailoop check-task-file ./loop_tasks.md\nailoop run \"Work the task list.\" --runner opencode --agent orchestrator --task-file ./loop_tasks.md --until-tasks-complete\n```\n\nWatch:\n\n```bash\nailoop ps\nailoop tail \u003cloop-id\u003e\nailoop --json ps\n```\n\nControl:\n\n```bash\nailoop pause \u003cloop-id\u003e\nailoop resume \u003cloop-id\u003e\nailoop stop \u003cloop-id\u003e\n```\n\nInspect:\n\n```bash\nailoop status \u003cloop-id\u003e\nailoop stats \u003cloop-id\u003e\nailoop logs \u003cloop-id\u003e\nailoop --json status \u003cloop-id\u003e\n```\n\nPresets + replay:\n\n```bash\nailoop memory save \"Quick review\" \"Review the repo.\" --runner opencode --agent orchestrator\nailoop memory list\nailoop memory show \u003cmemory-id\u003e\nailoop replay \u003cmemory-id\u003e\n```\n\n## Task file mode ✅\n\nGenerate a valid task file:\n\n```bash\nailoop task-template\nailoop task-template --with-rules\nailoop init-task-file ./loop_tasks.md\nailoop check-task-file ./loop_tasks.md\nailoop --json check-task-file ./loop_tasks.md\n```\n\nFormat:\n\n```md\n# Loop Tasks\n\n## To do\n- [ ] First task\n\n## Doing\n- None\n\n## Done\n- None\n```\n\nRules:\n\n- use only `To do`, `Doing`, `Done`\n- `To do`: only `- [ ] task` or `- None`\n- `Doing`: only `- [ ] task` or `- None`\n- `Done`: only `- [x] task` or `- None`\n- keep max 1 task in `Doing`\n- move task `To do -\u003e Doing` when start\n- move task `Doing -\u003e Done` and mark `[x]` when done\n\nExit codes:\n\n- `0`: valid and done\n- `10`: valid but still open (`--state-exit-code`)\n- `1`: invalid file\n\n## Commands 🧰\n\nCore:\n\n```bash\nailoop run \"Prompt\"\nailoop resume \u003cloop-id\u003e\nailoop pause \u003cloop-id\u003e\nailoop stop \u003cloop-id\u003e\nailoop replay \u003cmemory-id\u003e\n```\n\nMemory:\n\n```bash\nailoop memory save \"Title\" \"Prompt\"\nailoop memory save \"Recent run\" \"Prompt\" --kind history\nailoop memory list --kind preset\nailoop memory show \u003cmemory-id\u003e\nailoop memory edit \u003cmemory-id\u003e --title \"New title\"\nailoop memory favorite \u003cmemory-id\u003e\nailoop memory delete \u003cmemory-id\u003e\n```\n\nWatch + inspect:\n\n```bash\nailoop ps\nailoop tui\nailoop tui --tmux\nailoop list --active\nailoop status \u003cloop-id\u003e\nailoop stats \u003cloop-id\u003e\nailoop logs \u003cloop-id\u003e\nailoop tail \u003cloop-id\u003e\n```\n\nTUI memory smoke:\n\n```bash\nbash ./scripts/tui_memory_smoke.sh\ntmux attach -t ailoop-tui-smoke\n```\n\nTask files:\n\n```bash\nailoop init-task-file ./loop_tasks.md\nailoop check-task-file ./loop_tasks.md\nailoop check-task-file ./loop_tasks.md --state-exit-code\n```\n\nJSON + output modes:\n\n```bash\nailoop --json ps\nailoop --json status \u003cloop-id\u003e\nailoop --json logs \u003cloop-id\u003e\nailoop --quiet check-task-file ./loop_tasks.md\nailoop --verbose check-task-file ./loop_tasks.md\nailoop --color always status \u003cloop-id\u003e\n```\n\n## Config ⚙️\n\nDefault config path:\n\n```text\n~/.config/ailoop/config.yaml\n```\n\nExample:\n\n```yaml\ndefault_runner: opencode\ndefault_agent: orchestrator\n\npaths:\n  agent_file: ~/Codes/Projects/agents_md/AGENTS.md\n  state_dir: ~/.config/ailoop/state\n\nprompt:\n  pre_prompt_enabled: true\n  attach_agent_file: true\n  pre_prompt: |\n    Work in small validated slices.\n    Review current context before starting new work.\n    Leave concise progress, blockers, and next action at the end.\n\nloop:\n  steps: null\n  pause_seconds: 30\n  continue_on_error: true\n  retry_count: 0\n\nrunners:\n  opencode:\n    command: opencode\n    args: [\"run\", \"--agent\", \"{agent}\", \"{prompt}\"]\n  codex:\n    command: codex\n    args: [\"{prompt}\"]\n  claude:\n    command: claude\n    args: [\"{prompt}\"]\n```\n\n## Prompt assembly ✍️\n\nEach iteration prompt is assembled in this order:\n\n1. pre-prompt if enabled\n2. agent file contents if enabled\n3. user prompt\n4. loop context block with iteration and previous result summary\n\nPrompt and run logs are stored under the loop log directory for inspection.\n\n## Docs 📚\n\n- [docs hub](docs/index.md)\n- [GitHub Pages site](https://dmoliveira.github.io/ailoop/)\n- [config guide](docs/config.md)\n- [task-file mode](docs/task-file.md)\n- [examples](docs/examples.md)\n- [runners](docs/runners.md)\n- [hero banner brief](docs/branding/hero-banner-brief.md)\n\n## Support 💛\n\nIf `ailoop` saves you time, you can support ongoing maintenance and future releases here:\n\n- Stripe: https://buy.stripe.com/8x200i8bSgVe3Vl3g8bfO00\n\nBy Diego Marinho:\n\n- GitHub: [Diego Marinho](https://github.com/dmoliveira)\n- LinkedIn: [Diego Marinho](https://www.linkedin.com/in/dmoliveira/)\n\nMore: [docs/support.md](docs/support.md)\n\n## License 📝\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmoliveira%2Failoop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmoliveira%2Failoop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmoliveira%2Failoop/lists"}