pi-fleet

Cross-device orchestration for pi, terminal only. One pi extension that lets a pi instance on your main machine spawn, provision, watch, and steer pi sessions on any machine in your tailnet — no desktop app, no SSH, no cloud relay.

Server (your machine)                          Worker machines (tailnet)
---------------------                          -------------------------
pi (TUI) + pi-fleet [server mode]              pi-fleet agent [daemon]
  /serve                                         spawns pi --mode rpc
  bundle registry (skills/ext/tools)   --TCP-->  pi-fleet [worker mode]
  LLM fleet tools:                     tailnet     async factory pulls bundle
    remote_spawn / remote_prompt                   resources_discover -> skills
    remote_output / remote_abort                   registerTool / setActiveTools
    remote_exec / remote_exec_abort                direct Bash/PowerShell/argv (opt-in)
    fleet_status                                   full RPC control channel

Why

• pi as orchestrator: your local pi's LLM drives a fleet of remote pi workers through registered tools. "Spawn a worker on buildbox, fix the failing tests, report back" is a single prompt.
• Everything lives on the server: skills, extensions, tools, prompts, and model defaults are defined once in server-side bundles. Workers self-provision on spawn (content-hash cached), so there is no config drift.
• Tailnet-native: transport is plain TCP on the Tailscale interface. Identity comes free from tailscale whois — WireGuard-backed, no tokens, no pairing codes.
• Terminal only, cross-platform: pure TypeScript, no native deps. Linux, macOS, and Windows.

Design principles

Borrowed from studying Mosaic's cross-device architecture, adapted to pi's strengths:

1. Single-writer log, no CRDTs. A pi session is an append-only event log with one writer. Catch-up is snapshot-on-join (sessionManager.getEntries()), then live tail. No conflict resolution needed — steering input serializes through pi's own queue (steer / followUp).
2. Content-blind control plane. Frames are forwarded, never interpreted, by the transport layer.
3. Identity from the network, not the app. Tailnet membership + tailscale whois replaces session codes and token auth.
4. State lives at the edges. The server owns bundles; workers own their sessions; the wire carries only frames.

Modes

| Mode | Runs on | Role | |---|---|---| | server | your main machine, inside interactive pi | bundle registry, fleet tools for the LLM, control plane listener | | agent | each worker machine, as OS service | spawns/supervises pi --mode rpc processes on request | | worker | inside each spawned pi | bootstrap: pull bundle, provision skills/extensions/tools, expose RPC |

All three roles ship in one pi package. A machine can hold multiple roles at once.

Documentation

• Roadmap — phased delivery plan
• Implementation plan — components, protocol, milestones
• User stories
• Acceptance criteria
• State flow — lifecycle state machines and sequence flows

Install

Everything ships in this one package (runtime deps: typebox, jiti only; the pi package is a type-only devDependency, so production installs stay lean). Two roles, two install paths:

Same official command on every machine (pi clones to ~/.pi/agent/git/github.com/picassio/pi-fleet and runs a production npm install):

pi install git:github.com/picassio/pi-fleet

Server / orchestrator machine: that's it — the extension auto-loads in every pi session (fleet tools, /fleet-* commands).

Worker / agent machines — after the same pi install, open pi there and pick one:

/fleet-agent <your-server-tailnet-name>     # this pi session IS the agent (lives with the session)
/fleet-service <your-server-tailnet-name>   # install + start the durable agent service (systemd/launchd)

No curl, no scripts — the extension carries everything. For Claude Code subscription auth on workers, also pi install git:github.com/picassio/pi-cc-patch on that machine.

Direct machine control

Direct commands do not use workers or LLM tokens. They are disabled until enabled locally:

/fleet-agent <server> --exec-full
/fleet-service <server> --exec-full

Headless equivalent: pi-fleet-agent serve --server <server> --exec-policy full. Optional repeatable --exec-root values constrain only the command's initial working directory; they are not a filesystem sandbox. Full mode does not filter Bash/PowerShell, absolute paths, sudo, administrator operations, or system tools. Commands receive the permissions of the OS account running the agent. Use a privileged service account only when full machine administration is intended. See Remote execution plan.

curl -fsSL https://raw.githubusercontent.com/picassio/pi-fleet/main/scripts/bootstrap-agent.sh | sh -s -- --server <name> [--max-workers 4] [--with-cc-patch]

Workers spawned by the agent need no install at all — the agent injects its extension copy via -e, and they auto-load any pi packages installed on that machine.

Claude Code auth for workers: pass --with-cc-patch to the bootstrap (or pi install git:github.com/picassio/pi-cc-patch on the machine) so workers use your Claude Code subscription instead of API keys. The machine still needs Claude Code credentials present.

Workers spawned by the agent need no pi-fleet install of their own — the agent injects its extension copy via -e.

Prerequisites everywhere: Node ≥ 20, pi, Tailscale up; Windows additionally needs Git Bash (pi requirement).

Status

Pre-implementation. Design docs first, code second. See the roadmap.

License

MIT