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.

1. Install piloop

   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:

   uv tool install piloop
   piloop install-skills
   
2. 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.

3. Tell it what to improve

   Describe the goal in plain words. Say “piloop”, so that the agent uses the piloop skills:

   Use piloop to make our tokenizer faster without changing its output.
   

   Use piloop to improve the holdout accuracy of the model in train.py.
   

   Use piloop to make the test suite run faster. Do not delete or skip tests.
   

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:

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:

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.

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:

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:

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.

Next steps

• Several campaigns: one agent runs a campaign in each of your repos.
• The orchestrator and the inbox: how your agent decides and what it records.
• Running for days: keep the daemon running with a service manager.