piloop

Autoresearch for any git repo: coding agents try ideas, piloop scores every commit and keeps what wins.

Documentation: piloop.autoresearch.inc

You talk to one coding agent. It sets up a campaign in your repo and runs it for you. Coding agents try ideas in parallel, each one in its own git worktree. piloop runs your evaluate command on every commit. It keeps a change only when the change beats the best result so far. When your evaluate command reports a result for each example, the gain must also hold with statistical confidence.

The enwik8 example after 10 implementer runs: Claude Code agents took the first 10 MB of Wikipedia from 3,688,770 bytes (zlib) to 2,361,893 bytes (−36%) in 1.6 hours.

piloop keeps its state on your machine: a SQLite database and the run directories in PILOOP_HOME (~/.piloop by default), and every candidate commit as a git ref in your repo. piloop has no hosted service. The coding agents send your code and their prompts to their model providers, as they do when you use them yourself.

Start

1. Install piloop and its skills for your coding agents:

   curl -fsSL https://raw.githubusercontent.com/hiloopai/piloop/main/install.sh | sh
   

2. Open your coding agent in your repo: Claude Code, Codex, pi, Gemini CLI or Cursor.

3. Tell it what to improve. 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.
   

What happens next

1. Setup. The agent checks your machine and asks you a few questions: the metric, how to measure it, what must not get worse, which files the agents may edit, and the budget. Then it writes brief.md, piloop.toml and the evaluate command, measures the baseline and starts the campaign.
2. The campaign runs. Implementer agents try ideas. piloop scores each commit and keeps what wins. A research agent adds ideas, and a watchdog agent looks for problems.
3. The agent reports. Your agent answers what the other agents escalate and records each decision in your inbox. It asks you only what needs you. Ask it "how is the campaign going?" at any time.

To look at the campaign yourself, run piloop watch.

Try it on an example

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.

piloop init --example enwik8 ~/piloop-enwik8
cd ~/piloop-enwik8
piloop idea add enwik8 "Try lzma at the highest preset"
piloop serve --detach
piloop watch

Requirements

• Linux or macOS.
• git 2.40 or later, with a commit identity.
• uv. The installer installs it.
• At least one implementer agent CLI, logged in: Claude Code, Codex or pi.
• Optional: Herdr, to see and steer every agent in a terminal pane. By default, the agents run in the background. To use Herdr, set runtime = "herdr".
• Optional: Entire, to keep the session of every agent in your repo.

Documentation

• Introduction: what piloop does, and how a campaign works.
• Quickstart: your first campaign, through your agent.
• Concepts: campaigns, ideas, runs, candidates and the verdict.
• Reference: the CLI, the configuration, the database schema.

Contributing

See CONTRIBUTING.md. Agents that operate piloop start at AGENTS.md.

License

MIT. See LICENSE.