Skip to main content
Run piloop --help for the list of commands, and piloop <command> --help for the options of one command. Many commands take a REF: a project name, or a path inside the project’s repo. When a command makes the REF optional and you leave it out, it uses the project of the current directory, else the only active project, else every project. Commands that write sign their writes with PILOOP_ACTOR (human by default). See Environment variables.

​
Set up

​
piloop init

Makes PATH (default .) a piloop project and registers it. It is safe to run again.
  • Runs git init and makes a baseline commit when necessary.
  • When there is no piloop.toml, writes piloop.toml, brief.md and evaluate.py from the template. It keeps files that exist already. While evaluate.py is the unchanged stub, it stops and says what to edit.
  • Measures HEAD as the baseline candidate and registers the project. When the project is registered already, it reads piloop.toml again.
--example creates a bundled example instead of the blank template.

​
piloop install-skills

Copies the skills of this CLI into the skill directory of every harness on your PATH: ~/.claude/skills for Claude Code (or $CLAUDE_CONFIG_DIR/skills), and ~/.agents/skills for Codex, pi, Gemini CLI and Cursor. It replaces only piloop’s own skills. The installer and piloop upgrade run it.

​
piloop doctor

Checks the install, without changing anything. Each failure prints the command that fixes it. See Upgrading.

​
piloop upgrade

Upgrades the CLI, the skills and the database, and restarts a running daemon in place. --timeout (default 30) is how long to wait for the daemon to come back. See Upgrading.

​
piloop migrate

Brings the database to the schema of this CLI and prints what changed. Every command does this silently when it starts.

​
The daemon

​
piloop serve

Runs the daemon in the foreground. --detach starts it in the background, with its output in $PILOOP_HOME/serve.log. Only one daemon runs for each PILOOP_HOME.

​
piloop stop

Sends SIGTERM to the daemon and waits up to --timeout seconds (default 30) for it to exit. The daemon stops the running agents, and their runs fail with daemon stopped.

​
piloop restart

Restarts the running daemon in place on the installed code. The process keeps its pid, its environment and its service manager. The running agents continue, and the new code connects to them again. --timeout (default 30) is how long to wait for the daemon to come back.

​
piloop service-unit

Prints a systemd user unit (Linux) or a launchd agent (macOS) that keeps piloop serve running. It installs nothing. See Running for days.

​
Ideas and candidates

​
piloop idea add

Adds a defined idea. A ready idea runs when a worker slot is free, in order of priority. A watchdog files a seed instead. A worker files neither.

​
piloop idea seed

Files a seed: a hunch in one line, with pointers to what prompted it. The research agent develops it into an idea, or rejects it. See Seeds.

​
piloop idea develop

Develops a seed into a defined idea. Every one of these is required: Optional: --plan, --title, --family, --base, --priority (default: the seed’s) and --proposed.

​
piloop candidate import

Registers the tree of a commit, branch or tag of the repo as a reference candidate: a starting point that an idea can pin with --base. The daemon measures it. It is never kept, never the head and never a bar. To import a candidate of another project, fetch its commit into this repo first: git fetch <its repo> <sha>.

​
piloop candidate note

Keeps a measured discard or interesting candidate in view as a starting point. Its verdict becomes interesting, with the reason note: <REASON>. Each --follow-up files a seed pinned to the candidate. See Notes.

​
Status and the inbox

​
piloop status

Prints the daemon’s state, then for each project: the head, the tracks, the trajectory, the progress against [stop], the open runs, the queue, the running agents with their last line, the recent candidates, the anomalies, the inbox, the latest decisions and the recent events. The watchdog and research agents get the same overview in their brief.

​
piloop watch

Shows the campaign on one screen, with keys to act on it. See Watching a campaign.

​
piloop history

Prints the research pack: the metrics, the ideas by source, the analysis files, what was tried for each mechanism, every idea with its outcome, the kept lineage, the findings, the digests and the open escalations. A research sweep reads it before it proposes ideas.

​
piloop inbox

Lists the unacknowledged items addressed to you, most urgent first. --kind keeps only items of one kind: note, finding, decision or escalation. --all includes acknowledged items. See The orchestrator and the inbox.

​
piloop inbox show

Prints one item, then the comments linked to it: the comments it cites, the comments that cite it, and its replies.

​
piloop inbox ack

Acknowledges items: you have seen them. --up-to acknowledges every unacknowledged item up to that id instead. Nothing waits on an acknowledgement. To revise a decision, write a decision comment on its target.

​
piloop inbox wait

Blocks until something needs the orchestrator, then prints it, one line each, and the command for the next wait. It returns for a new inbox item that someone else wrote, a project that the daemon stopped, an anomaly that the daemon gave to a watchdog, and the daemon’s verdict on a measured candidate. --after is the cursor that the last wait printed (default: now). --timeout (default 1800) is how long to wait before it returns with nothing. Set the timeout of your shell tool above it.

​
Agents

​
piloop launch

Asks the daemon for one more agent of ROLE: watchdog or research. The daemon starts it on its next tick, within the role’s max_concurrent. --scout asks for a research sweep in scout mode. Only the daemon starts workers, because a worker needs a run.

​
piloop attach

Focuses the agent’s tab in the piloop Herdr session and attaches this terminal to it.

​
piloop prompt

Types TEXT into a running agent of any role. This needs the Herdr runtime. The worker ids are in piloop status.

​
The database

​
piloop sql

Runs one SQL statement against the piloop database. Schema changes and transactions are denied. Everything else, including DELETE, is allowed. See the database schema.

​
piloop schema

Prints what piloop sql accepts, the conventions for writing to the database, and every table. Agents read it before they write.