> ## 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.

# Quickstart

> Install piloop, open your coding agent in your repo and tell it what to improve. The agent does the rest.

You run piloop through one coding agent. You tell it the goal in plain words. It sets up the campaign, starts it and
runs it for you.

<Steps>
  <Step title="Install piloop">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/hiloopai/piloop/main/install.sh | sh
    ```

    The installer installs uv, Entire, the `piloop` CLI and the piloop skills for every coding agent on your `PATH`.
    It is safe to run again. If you already have uv, you can install the CLI alone:

    ```bash theme={null}
    uv tool install piloop
    piloop install-skills
    ```
  </Step>

  <Step title="Open your agent in your repo">
    Start Claude Code, Codex, pi, Gemini CLI or Cursor in the repo that you want to improve. This agent is the only one
    that you talk to.

    The workers run on Claude Code, Codex or pi, so at least one of these must be installed. The agent that you talk
    to can be any of the five.
  </Step>

  <Step title="Tell it what to improve">
    Describe the goal in plain words. Say "piloop", so that the agent uses the piloop skills:

    ```text theme={null}
    Use piloop to make our tokenizer faster without changing its output.
    ```

    ```text theme={null}
    Use piloop to improve the holdout accuracy of the model in train.py.
    ```

    ```text theme={null}
    Use piloop to make the test suite run faster. Do not delete or skip tests.
    ```
  </Step>
</Steps>

## The setup

The agent follows the `piloop-setup` skill. It runs every command itself and reports each result in one line.

1. **It checks your machine:** git, uv, the coding agent CLIs and their logins. It fixes what it can. It asks you only
   to log in where a CLI needs a browser, and it asks for all the logins at the same time. It checks Herdr only if you
   want to see and steer every agent in a terminal pane.
2. **It reads your repo and interviews you.** It says what it learned from the repo, so you can correct it. Then it
   asks only what the repo does not answer. It writes no file before you answer or skip the interview.
3. **It writes the campaign:** `brief.md` for the workers, `piloop.toml` with the metrics and limits, and the evaluate
   command. It runs the evaluate command once and shows you both files. It asks you once more before it continues.
4. **It registers the project** with `piloop init .`. This measures the baseline. The agent tells you the baseline
   value. A value that surprises you usually means that the evaluate command is wrong.
5. **It starts the daemon** with `piloop serve --detach`. It adds the first ideas with you, or asks a research agent
   for ideas.
6. **It becomes the orchestrator.** It asks if it should run the campaign in this session or in a background
   subagent, so that your session stays free.

### What the interview asks

The questions fit your problem. A typical interview covers these topics:

| Topic | The agent asks |
| - | - |
| Objective | The one metric to improve, its direction, and what "done" is: a target, a deadline or a budget. |
| Measurement | The command that measures it, how long it takes, and how much the result changes between identical runs. |
| Guardrails | What must not get worse, such as latency, size or cost, and by how much it may. |
| Scope | The files that workers may edit, the files they must not touch, and forbidden techniques. |
| Budget | The time per run, the number of workers at the same time, and the total runs, hours or dollars. |
| Prior art | What you tried already and what you expect to work. |
| Agents | Which coding agents and models run the workers and the research. |
| Escalation | What the agent must ask you about, and what it may decide alone. |

The agent puts each limit in `piloop.toml`, so that the daemon enforces it. A limit that is only in `brief.md` is not
enforced.

## While the campaign runs

Workers try ideas in their own git worktrees and commit. piloop scores every commit and keeps the ones that beat the
best result so far. Your agent waits on the inbox with `piloop inbox wait`, so it uses no tokens while nothing
happens. When something needs it, it acts:

* It answers escalations from the other agents.
* It adds ideas, changes their priority and asks for research or watchdog sweeps.
* It records each decision that it takes for you in your inbox, with the reason and how to revert it.
* It leaves for you the decisions that cannot be undone and can wait.

When you are present, the agent reports at least every hour: the head against the baseline, what ran, and what it
decided. When the campaign stops, it reports the result.

## Check in later

Ask your agent:

```text theme={null}
How is the campaign going?
```

Any agent with the piloop skills can answer, also in a new session. It reads `piloop status`.

To look yourself, run:

```bash theme={null}
piloop watch
```

`piloop watch` shows the inbox, the agents, the ideas and the candidates. Press `r` on an inbox item to reply to a
decision. Your agent applies your reply first. See [Watching a campaign](/guides/watch).

## Stop

The campaign ends by itself at the limits in the `[stop]` table of `piloop.toml`, for example after a number of runs.
To end it earlier, lower a limit in `[stop]` and run `piloop init` again, or ask your agent to do it.

To pause every campaign, stop the daemon:

```bash theme={null}
piloop stop
```

`piloop stop` stops the daemon and every agent that it runs. The ideas of the stopped runs go back to the backlog.
The projects stay active, and the next `piloop serve --detach` continues them. Every candidate commit stays in the
repo under `refs/piloop/`, so `git show` and `git cherry-pick` work on any of them.

## Try it on an example

To see a campaign before you use your own repo, ask your agent:

```text theme={null}
Set up the enwik8 example campaign from piloop.
```

The agents compress the first 10 MB of Wikipedia, as in the Hutter Prize. The baseline is zlib at level 9. The example
stops after 20 scored worker runs. To run it without an agent, see [Run a campaign by hand](/by-hand).

## Next steps

* [Several campaigns](/several-campaigns): one agent runs a campaign in each of your repos.
* [The orchestrator and the inbox](/concepts/orchestrator): how your agent decides and what it records.
* [Running for days](/guides/running-for-days): keep the daemon running with a service manager.


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