Agent Fleet

Operate a coding-agent fleet — not just one chat session.

Agent Fleet is a multi-agent orchestration system for AI coding agents, built pi-first: a thin dispatcher routes work to specialist agents under a Verification Contract, whole teams spawn as tiled workspaces you can snapshot and resume, agents message each other over a shared coms plane, a Hermes Desktop panel shows you the whole fleet at a glance — and a library of 29 production-grade lifecycle skills and 15 personas keeps every agent disciplined.

Three things make it unusual:

1. You run it on the subscriptions you already pay for — Codex/ChatGPT, GitHub Copilot, Claude, Ollama — mixed inside one fleet, alongside models running locally on your own GPU. How ↓
2. The dispatcher never drowns. Research output, subagent dumps and specialist chatter stay out of the orchestrator's context window — on disk, behind file paths. How ↓
3. You can actually see it. Tiled panes in herdr, a live session panel in Hermes Desktop, and questions relayed to your phone when an agent needs a human. How ↓

One coding agent: pi. Everything installs for pi and nothing else. Claude Code appears throughout this README as a coms peer — a real Claude pane bridged into the fleet to answer other agents' questions and run cross-model review. That is its whole role; it is not an install target. The bridge ↓

The fleet at a glance

flowchart TD
    You(["<b>You</b><br/>terminal · desktop · phone"])

    subgraph Control["Control surfaces"]
        Herdr["<b>herdr</b><br/>tiled peer workspaces<br/>snapshot · resume"]
        Desktop["<b>Hermes Desktop plugin</b><br/>live session panel<br/>who is blocked · what it is doing"]
        Phone["<b>Hermes relay</b><br/>hub questions → Telegram<br/>answer from anywhere"]
    end

    Hub["<b>agent-hub</b> — thin dispatcher<br/>owns the Verification Contract on disk"]

    subgraph Team["Specialist team (.pi/agents/teams.yaml)"]
        Specialists["planner · plan-reviewer · builder<br/>test-engineer · code-reviewer · documenter"]
    end

    Research["<b>research helpers</b> — read-only<br/>findings go to disk, never to the dispatcher"]
    Coms["<b>coms</b> — peer data plane<br/>pi ⇄ pi ⇄ Claude Code panes"]

    You --> Control
    Control --> Hub
    Hub --> Specialists
    Specialists --> Research
    Hub <--> Coms
    Specialists <--> Coms
    Coms --> Desktop

Quick Start

Install into a repository

From the target repository. The first install goes through npx — just fleet does not exist yet, because the managed justfile region is one of the things setup writes:

cd ~/projects/my-app
npx @chankov/agent-fleet@latest setup

In a real TTY that opens the installer: pick the Default or Full preset and optional comma-separated features, read the exact reconciliation plan, then confirm once. For automation, name the selection and consent:

npx @chankov/agent-fleet@latest setup --preset default --features none --yes

Default is a launchable stable Fleet Core; it creates neither .claude/ nor voice configuration. Full selects all stable platform-applicable catalogue roots and may install the recorded Claude Code coms bridge. The lifecycle requires no coding agent or model.

Setup writes files but never runs commands, so finish with the two npm steps it deliberately skipped — the workspace is not launchable until they run:

just fleet deps     # npm install in .pi/extensions and .pi/harnesses
just fleet doctor   # exit 0 = nothing to repair

Then start a fleet:

just fleet                                      # Hub/operator; direct tools; empty native roster
just fleet --agents frontend                    # Hub/orchestrator + native specialists
just fleet --agents frontend --peers frontend --project af
                                                # same Hub + standing peers in Herdr

Updating

A pi session prints a banner when a newer version is published. Your preset and features live in .ai/agent-fleet.json, so a plain setup reconciles to the selection you already made:

just fleet setup --dry-run    # preview: what changes, what gets overwritten
just fleet setup              # apply; shows the plan and asks once
just fleet deps               # if the plan skipped the npm steps
just fleet doctor

setup reconciles toward the package. A shipped artifact you edited in place is refreshed and your edit is overwritten — no prompt. Customize through .ai/agent-fleet-overrides.md, which no lifecycle command touches. If both you and the new version changed the same file, setup exits 3 having written nothing; re-run with --on-conflict theirs or --on-conflict ours.

pi update --extensions updates pi's own extensions only — never this installer or what it wrote. just fleet install was removed; use setup or deps.

just fleet setup/doctor/uninstall are thin wrappers over npx @chankov/agent-fleet@latest for a workspace that already has the justfile. just fleet uninstall --yes removes its own launcher last, so reinstall afterwards with the package CLI.

Full reference: docs/npm-install.md and the major-release migration matrix.

git clone https://github.com/chankov/agent-fleet.git && cd agent-fleet
node bin/cli.js setup --workspace ~/projects/foo --preset default --features none --yes

Versioned with semver — CHANGELOG.md · docs/npm-install.md.

Bring your own subscriptions — and your own GPUs

There is no Agent Fleet API key. Every agent in the fleet declares which model it wants, and pi resolves that against whatever providers you are already signed in to. A single fleet routinely mixes several at once — that is the normal configuration, not an edge case.

Two consequences worth spelling out:

• Cross-model review is the point, not a party trick. A builder on one lab's model and a code-reviewer on another's catches what a single model rationalizes past. plan-reviewer and code-reviewer ship ready to run as Claude Code peers for exactly this.
• Cost lives on a ladder, not a switch. Each persona declares a default plus a switch list over a three-tier policy — deep reasoning / workhorse / fast recon — swappable at runtime per persona (/af-agent-model) or fleet-wide (/af-models <profile>). Recon sweeps run on the cheap tier or on your own hardware; only synthesis and verdicts spend the expensive one.

/af-models fast                                   # move the whole team down a tier
/af-agent-model builder github-copilot/claude-sonnet-4.6
/af-agent-models-substitute openai-codex/gpt-5.6-sol ollama/glm-5.2:cloud   # swap one model everywhere

Per-project defaults live in .ai/agent-fleet-overrides.md — see docs/agent-fleet-setup.md.

Watch the fleet from your desktop — the Hermes plugin

Once a fleet is more than two agents, "is anything waiting on me?" stops being answerable by looking at panes. agent-fleet-herdr is an in-repo Hermes Desktop plugin that answers it: a live panel of every Agent Fleet session, grouped by project, sorted so that the agent blocked on a human is at the top.

What the panel gives you

• Every session, not every pane. The list is built from the coms registry, so an agent that left its herdr pane still shows up — as detached, which is a different fact from "gone".
• A toast when something needs you. needs_answer (an agent blocked on a human for more than 20s), vanished (a session that died mid-work), stale, finished — pushed over a WebSocket, with a poll underneath that never switches off. Optional Telegram fan-out for alerts that must survive a closed window.
• What an agent is doing right now. Select a row and the modal reads that agent's own transcript — bash git rev-list…, dispatch_agent builder, update_assertion — projected through a per-tool allowlist, never forwarded wholesale.
• The subagents underneath it. A hub whose own transcript is idle while three specialists work is exactly the case a naive status panel renders as "nothing happening". Each live child carries a tail of its stdout and a Cancel button.
• One action, and honest disabled states. Focus pane brings the workspace hosting that agent to the front. An action that cannot work right now stays visible with its reason beside it.

How it connects to Agent Fleet

The plugin reads what the fleet already writes. It adds no daemon to your agents and holds no write door into them.

flowchart LR
    subgraph Fleet["Your running fleet"]
        Agents["pi + Claude Code peers"]
        Registry[("~/.pi/coms/projects/*<br/><b>coms registry</b><br/>who exists")]
        Transcripts[("~/.pi/agent/sessions<br/>~/.claude/projects<br/><b>transcripts</b><br/>what it is doing")]
        HerdrD["<b>herdr</b><br/>what state it is in"]
        Agents --> Registry
        Agents --> Transcripts
        Agents --> HerdrD
    end

    subgraph Hermes["Hermes"]
        API["<b>backend</b> — FastAPI<br/>plugins/agent-fleet-herdr/dashboard<br/>join · watch · project"]
        Pane["<b>Desktop pane</b> — ESM<br/>desktop-plugins/agent-fleet-herdr"]
        API -->|"REST + WS"| Pane
    end

    Registry --> API
    Transcripts --> API
    HerdrD --> API
    Pane -->|"POST focus"| HerdrD

• The coms registry is the filter and the source of truth for who exists. A herdr pane with no registry entry is not an Agent Fleet session and is not shown.
• herdr says what state each one is in, joined by the (project, name) pair a pane advertises — not by cwd, which a pi pane and a Claude Code pane in the same repo would collide on.
• The agent's own transcript says what it is doing. That file is written whether or not anybody is watching, which is why the activity tail also works for a detached session no pane hosts.
• Reads only, except two doors. focus and subagent cancel — both re-derived server-side from a fresh snapshot, so a renderer cannot name a target it was not given.

Install it

Prerequisites: Hermes v0.19.0+ (the hermes CLI on PATH, plus the Desktop app), this repo checked out, and a fleet that has run at least once (so ~/.pi/coms/projects/ exists). herdr is optional — without it every row reads unknown instead of a live state.

scripts/install-hermes-plugin.sh agent-fleet-herdr

That one command backs up config.yaml, symlinks both halves into the profile (plugins/ for the FastAPI backend, desktop-plugins/ for the pane), runs hermes plugins enable, and verifies the result — then prints the restart steps instead of performing them, because restarting a live gateway is your call:

# 1. restart the Hermes Desktop app  ← the pane talks to the gateway Desktop spawns for itself
# 2. hermes gateway restart          ← only if the web dashboard / TUI needs the routes too

Then start a fleet and open the Agent Fleet tab:

just fleet --agents default --peers default    # monitored Hub + peers; nothing extra to configure

scripts/install-hermes-plugin.sh agent-fleet-herdr --profile dev   # a non-default profile
scripts/install-hermes-plugin.sh agent-fleet-herdr --copy          # no symlinks
scripts/install-hermes-plugin.sh agent-fleet-herdr --dry-run       # print, change nothing
scripts/install-hermes-plugin.sh agent-fleet-herdr --uninstall

Deep dive: docs/hermes-desktop-plugins.md — the plugin contract, the four rules that cost the most to learn, the full API, and the deliberate limits.

And on your phone

Separately from the panel, the Hermes relay pipes an agent's ask_user question — choices intact, not flattened into a message — to Telegram, and races your phone's answer against a local one. Whichever arrives first wins; the fleet keeps working meanwhile.

See docs/coms-hermes-bridge.md and the screenshots.

cd /path/to/agent-fleet
just fleet conductor codex setup docs --project af  # once per configured context
just fleet conductor codex pair                     # interactive; never capture the code
just fleet conductor codex start
just fleet --agents default --peers docs --project af # Hub + peers Codex can reach

agent-hub: a thin-context dispatcher for pi

Every public Pi Fleet session is now one agent-hub runtime with two postures. Bare just fleet starts in operator posture: direct read/bash/edit/write, orchestration tools, embedded coms, and an empty native roster. Orchestrator posture removes direct coding tools and drives specialist subagents — planner, builder, reviewer, test-engineer, documenter — under the Verification Contract. Both postures keep the same Hub commands, research helpers, peer collaboration, and damage-control-continue guardrails.

What makes it different is what it doesn't put in front of the dispatcher LLM. Multi-agent setups usually drown the orchestrator: every subagent's output, every research dump flows back into one context window until it compacts and forgets. agent-hub is built the other way around:

• Research never enters the dispatcher context. Specialists end their turn with NEEDS_RESEARCH: lines; the hub fans out read-only helpers, writes findings to disk, and resumes the specialist with file paths. The dispatcher sees a one-line notice — never the raw findings. Each local-disk research tool call has a parent-side 120-second watchdog (configurable as recon-search-timeout-s in .ai/agent-fleet-overrides.md), not a whole-agent deadline.
• The Verification Contract lives on disk. A ledger of checkable acceptance assertions, built from the request before any builder runs, rendered as one status line (Assertions: 2✓ 1○ 1✗ · open: A4). A stated requirement is never silently dropped, and the contract survives compaction.
• Specialists run --no-extensions. Tools and credentials stay scoped to the subagent that needs them instead of leaking up into the dispatcher.

just fleet                                      # operator; empty native roster
just fleet --agents frontend                    # native roster; orchestrator inferred
just fleet --posture operator --agents frontend # direct work plus the same roster
just fleet --no-coms                            # direct/native work; no peer messaging

# live posture and roster changes preserve the session
/af-agents-add code-reviewer
/af-posture orchestrator
/af-posture operator

# Herdr topology (requires a running server — https://herdr.dev)
just fleet --herdr --project af
just fleet --agents frontend --peers frontend --project af

Native specialists are local headless Pi subprocesses; standing peers are separate Pi or Claude Code processes in sibling Herdr panes. They can share a name without ambiguity: dispatch_agent(..., backend: "native") always starts the local Pi specialist, backend: "coms" requires the live peer, and backend: "auto" follows .pi/agents/dispatch-policy.yaml.

From a Hub pane, add a declared Claude reviewer with herdr_spawn_peer({ name: "code-reviewer" }), then use coms_send + coms_await; the peer is locked to the Hub's project. /af-handoff code-reviewer works in either posture when that peer is visible in the coms pool. Herdr operations require a live Herdr server; peer messaging/handoff require coms readiness. All Hub slash commands remain registered in both postures and unavailable capabilities refuse with remediation instead of disappearing.

Compatibility forms (just fleet hub, just fleet team <preset>, and --solo) remain accepted during migration and print canonical replacements; use --no-coms instead of --solo.

Deep dive: agent-hub harness README (the full dispatch loop, coms layer, configuration) · fleet hierarchy · pi extension catalog · Claude Code coms bridge · Hermes bridge.

The lifecycle: commands and skills

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
 │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
  spec           plan           build         test          review        ship

Slash commands map to the development lifecycle; each activates the right skills automatically. They install into .pi/prompts/ under the /af-* namespace, so they never collide with a command your workspace already defines.

Under the hood are 29 skills — each a structured workflow with steps, verification gates, and anti-rationalization tables (never vague advice). Skills also activate automatically from what you're doing: designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering.

• Define: interview-me · idea-refine · spec-driven-development
• Plan: planning-and-task-breakdown
• Build: incremental-implementation · test-driven-development · context-engineering · source-driven-development · doubt-driven-development · frontend-ui-engineering · api-and-interface-design
• Verify: browser-testing-with-devtools · debugging-and-error-recovery
• Review: code-review-and-quality · code-simplification · security-and-hardening · performance-optimization
• Ship: git-workflow-and-versioning · ci-cd-and-automation · deprecation-and-migration · documentation-and-adrs · observability-and-instrumentation · shipping-and-launch
• Orchestrate: orchestration-verification · peer-coms
• Learn: compound-learning · Meta: using-agent-skills · designing-agents

Workspace onboarding uses the deterministic setup, doctor, and uninstall CLI lifecycle.

Full catalog with descriptions and triggers: docs/skills-catalog.md. Format spec: docs/skill-anatomy.md.

Agent personas

15 pre-configured specialist personas live in agents/ — reusable subagent definitions your coding agent delegates work to: planner, plan-reviewer, builder, code-reviewer, test-engineer, security-auditor, web-performance-auditor, documenter, architect, releaser, researcher, deep-researcher, plus the pi-only bowser, web-debugger, and orchestrator.

Each persona is one Markdown file in pi's own frontmatter dialect, installed verbatim — there is no per-agent translation step. Personas are the who, skills are the how — each carries a conditional hook to its primary skill, and they compose into teams under the hub.

Full roster, skill hooks, install matrix, and team composition: docs/agents.md.

Why Agent Fleet?

One coding agent is an assistant; a fleet is a team you operate. Agent Fleet exists for the moment a single session stops being enough — when you want a dispatcher driving specialists under a Verification Contract, whole peer teams you can snapshot and resume, Claude Code panes that answer pi agents mid-task, a desktop panel that tells you which agent is stuck, and a phone-reachable human in the loop.

Discipline is the other half. AI coding agents default to the shortest path — skipping specs, tests, and security reviews. The skill library gives every agent in the fleet the same discipline senior engineers bring to production code, baking in practices from Software Engineering at Google and Google's engineering practices guide: Hyrum's Law in API design, the test pyramid and Beyonce Rule in testing, change sizing in review, Chesterton's Fence in simplification, trunk-based development in git workflow.

How it compares: wondering how this stacks up against Superpowers or Matt Pocock's skills? See docs/comparison.md — an honest, side-by-side look, including a controlled head-to-head experiment.

Documentation

Credits & origins

Agent Fleet started as a customized fork of Addy Osmani's agent-skills library, with pi session-harness patterns from IndyDevDan's pi-vs-claude-code (MIT) growing alongside it. As orchestration became the center of gravity, it split into a standalone project — with the upstream relationship kept honest: Addy's library is vendored pristine at a pinned SHA under vendor/agent-skills-upstream/ (policy), and the ported harnesses credit their origin in docs/pi-extensions.md.

Thank you both for the inspiration and for shipping work others can build on.

Contributing

Skills should be specific (actionable steps), verifiable (clear exit criteria with evidence), battle-tested (based on real workflows), and minimal (only what's needed to guide the agent). See docs/skill-anatomy.md and CONTRIBUTING.md.

License

MIT - use these skills in your projects, teams, and tools.