Introduction

loopy-loop runs long-running AI agent workflows inside your repository. It turns a goal file into an inspectable sequence of agent iterations — plan, implement, evaluate, record evidence, and continue — until the goal is met or the loop hits a terminal blocker.

It is a small Python CLI plus a FastAPI coordinator and one or more workers. The coordinator owns the loop state and decides the next workflow; the workers execute assignments through team-harness, which can delegate to agent CLIs such as Codex, Claude Code, and Gemini.

Why loopy-loop

The value is control and durability. Instead of asking one agent to solve a large task in a single fragile chat, loopy-loop gives the work a home in your repo:

• Durable state in git and files. Continuity comes from your git history plus files under .loopy_loop/sessions/<session_id>/, not from a chat transcript you can't audit. You can pause, resume, and inspect every prompt/result pair.
• Repeatable workflow prompts. Each iteration runs one named workflow whose prompt lives in your repo and is version-controlled like any other source.
• Explicit stop conditions. The loop stops when a workflow says so through a session-scoped control file, or when it exhausts its turn budget — never by guesswork.
• Structured logs. Every iteration writes its rendered prompt, normalized result, and a link to the underlying harness output, so you can see exactly what happened and why.

The actual project changes still land where they belong: normal git branches and pull requests.

Who it's for

loopy-loop is for developers who want to point capable coding agents at a substantial, well-specified goal and let them work across many iterations without losing visibility or control. If you can describe a target with observable completion criteria — and you want the work to be resumable, auditable, and reviewable — this is built for you.

Where to go next

• Getting Started — install the CLI, scaffold a repo, and run your first loop.
• Concepts — the coordinator/worker model, the iteration loop, and the session directory as durable state.
• Configuration — the root loopy_loop_config.yaml and every team_harness_* setting.
• Workflows — workflow sets, scheduling fields, and the three shipped templates.
• Success & Control and Evaluation — how the loop decides it is done.
• Reference: Session Layout, HTTP Contract, and CLI Reference.

The source lives on GitHub and the package is published to PyPI.