Skip to main content

​
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, and it runs piloop for you.

​
Who adds ideas

Anyone can add to the queue. Each actor sees different information, so each one adds a different kind of idea. 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 has the details.

​
The components

  • The CLI (piloop) is how people and agents act: piloop idea add, piloop sql, piloop inbox wait, piloop status. See the CLI reference.
  • 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.
  • 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 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 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.
  • One run’s life: what happens between a ready idea and a verdict.
  • State machines: the statuses of ideas, runs, agents and candidates.
  • Code layout: the subpackages of piloop and how they depend on each other.
  • Extension points: add a runtime, a harness, an MCP server or an evaluate command.