> ## Documentation Index
> Fetch the complete documentation index at: https://piloop.autoresearch.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> piloop is a daemon that runs a queue of ideas through existing coding agents, and keeps only what beats the best result so far.

## The core idea

piloop is a daemon that manages a queue of ideas. Each idea becomes a **run**: a coding agent tries the idea in its own
git worktree and commits. The evaluate command measures each commit. The verdict keeps a commit only when it beats the
**head**, the best result so far. That is the whole loop.

piloop is an orchestrator on top of existing coding agents: Claude Code, Codex and pi. It is not a new agent harness.
The companies that train the models tune their own harnesses hard for this kind of work. piloop runs the harnesses as
they are, so it gets their best features at no cost.

The design optimizes three things, in this order:

1. **The best final result.** A commit is kept only when its gain is statistically real and every guardrail metric
   holds.
2. **Reaching that result fast.** The daemon runs the most urgent ideas first, several at a time.
3. **A short experiment loop.** Each run starts in a fresh worktree of the head. The worker slot is free again as soon
   as the agent ends, while the daemon measures the commits.

The state is one SQLite file. Agents read and write it with plain SQL through `piloop sql`, and the skills use the
same CLI. There is no API server: this is the simplest thing that works.

You do not manage a swarm of agents. You talk to one agent, the [orchestrator](/concepts/orchestrator), and it runs
piloop for you.

```mermaid theme={null}
flowchart LR
    you(("You")) <--> orch["Orchestrator<br/>(your agent)"]
    you -->|ideas, seeds| queue[("Idea queue")]
    orch -->|ideas, seeds, priority| queue
    research["Research agent"] -->|ideas, developed seeds| queue
    watchdog["Watchdog agent"] -->|seeds| queue
    queue --> daemon["Daemon"]
    daemon -->|one run per idea| worker["Worker agent<br/>in its own git worktree"]
    worker -->|commits| evaluate["Evaluate command"]
    worker -->|findings| research
    evaluate -->|metrics| verdict{"Verdict"}
    verdict -->|keep| head["Head"]
    head -->|the next runs start here| worker
```

## Who adds ideas

Anyone can add to the queue. Each actor sees different information, so each one adds a different kind of idea.

| Actor | What it adds or changes | What it sees |
| - | - | - |
| You | Ideas and seeds. The priority and status of any idea. | Everything: `piloop watch`, `piloop status`, the inbox. |
| Orchestrator | Ideas and seeds. The priority and status of any idea. | The inbox and the project status. |
| Research | Develops each seed into an idea or rejects it. Adds ideas of its own, with a priority. | The project overview and the research pack: what was tried, by family, and every finding. |
| Watchdog | Seeds, for example a retry that avoids a failure. Escalations for the orchestrator. | The project overview, and the research pack or the incidents to investigate. |
| Worker | A hunch in its `finding` comment. Research reads it. A worker files no ideas or seeds. | Its brief: its idea, its starting point, the comments on the idea, and the history. |
| Daemon | Puts an idea back in the queue when its run failed and attempts are left. Files a seed when a rebase conflicts. Rejects an idea that a newer one supersedes before it ran. | The database. |

Research and the watchdog do not change the priority or the status of ideas that they did not file. The orchestrator
and you do. [Ideas, seeds and runs](/concepts/ideas-and-runs) has the details.

## The components

```mermaid theme={null}
flowchart LR
    human["You<br/>piloop watch"]
    orch["Orchestrator<br/>any coding agent with<br/>the piloop-operate skill"]
    cli["piloop CLI"]
    db[("SQLite database<br/>$PILOOP_HOME/piloop.db")]
    subgraph daemon["Daemon: piloop serve"]
        scheduler["Scheduler<br/>one tick every 2 seconds"]
        executor["Run executor"]
        launcher["Launcher"]
    end
    runtime{{"Runtime<br/>subprocess or herdr"}}
    subgraph agents["Agents: a harness in a git worktree"]
        worker["worker"]
        research["research"]
        watchdog["watchdog"]
    end
    evaluate["Evaluate command<br/>prints METRIC lines"]
    repo[("Project repo<br/>refs/piloop/")]

    human --> cli
    orch --> cli
    cli -->|SQL| db
    daemon -->|SQL| db
    scheduler -->|worker runs| executor
    scheduler -->|research and<br/>watchdog sweeps| launcher
    executor --> launcher
    launcher -->|harness argv, brief| runtime
    runtime --> agents
    agents -->|piloop sql| cli
    agents -->|commits| repo
    executor -->|a clean worktree<br/>per commit| evaluate
    executor -->|pins, rebases| repo
```

* **The CLI** (`piloop`) is how people and agents act: `piloop idea add`, `piloop sql`, `piloop inbox wait`,
  `piloop status`. See the [CLI reference](/reference/cli).
* **The database** is the contract between every actor. Its tables, CHECK constraints and triggers hold the rules:
  the allowed values, who changed a row last, a log of every change, and full-text search. An authorizer refuses
  schema changes and transactions from `piloop sql`. See the [data model](/architecture/data-model).
* **The daemon** (`piloop serve`) is one process for each piloop home. On each tick, the **scheduler** checks the
  triggers of every project, queues runs of ready ideas and launches the requested agents. The **run executor** runs
  one run: the worktree, the agent, the scores, the verdict. The **launcher** starts, watches and closes every agent.
* **The runtime** is where an agent process runs: a background process by default, or a [Herdr](https://herdr.dev)
  pane that you can watch and steer.
* **The harness** is the coding agent CLI: Claude Code, Codex or pi. A `[harness.<name>]` table says how to start it.
* **The agents** each work in their own git worktree. A worker tries one idea. Research and the watchdog are
  [sweeps](/concepts/roles) that read the state of the campaign and write ideas, seeds and comments.
* **The evaluate command** is your program. The daemon runs it in a clean worktree of each commit and stores what it
  prints as a measurement.
* **The orchestrator** is any coding agent with the `piloop-operate` skill. It loops on `piloop inbox wait`. The
  daemon never starts it.

Everything runs on one machine: one SQLite file, one daemon, and local worktrees.

## Read next

* [One run's life](/architecture/run-lifecycle): what happens between a ready idea and a verdict.
* [State machines](/architecture/state-machines): the statuses of ideas, runs, agents and candidates.
* [Code layout](/architecture/code-layout): the subpackages of `piloop` and how they depend on each other.
* [Extension points](/architecture/extension-points): add a runtime, a harness, an MCP server or an evaluate command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.