export const metadata = {
  title: "Introduction",
  description:
    "loopy-loop runs long-running AI agent workflows inside your repository, with durable session state, repeatable prompts, and explicit stop conditions.",
};

# 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](https://fastapi.tiangolo.com/) coordinator and one worker. The coordinator owns the loop state and decides the next workflow; the worker executes assignments through [`team-harness`](https://github.com/writeitai/team-harness), which can delegate to multiple 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](/docs/getting-started) — install the CLI, scaffold a repo, and run your first loop.
- [Concepts](/docs/concepts) — the coordinator/worker model, the iteration loop, and the session directory as durable state.
- [Configuration](/docs/configuration) — the root `loopy_loop_config.yaml` and every `team_harness_*` setting.
- [Workflows](/docs/workflows) — workflow sets, scheduling fields, and the three shipped templates.
- [Success & Control](/docs/success-and-control) and [Evaluation](/docs/evaluation) — how the loop decides it is done.
- Reference: [Session Layout](/docs/session-layout), [HTTP Contract](/docs/http-contract), and [CLI Reference](/docs/cli-reference).

The source lives on [GitHub](https://github.com/writeitai/loopy-loop) and the package is published to [PyPI](https://pypi.org/project/loopy-loop/).
