Concepts
This page shows how fleetd’s parts fit together and what happens to a piece of work. Every term is also in the Glossary.
The parts
Section titled “The parts”| Part | What it is | How many |
|---|---|---|
| Hub | The coordinator. It stores all state and serves the app, the nodes and MCP clients on one port. | One per fleet, on an always-on machine. |
| Node | The fleetd process on a machine that runs agents. It connects out to the hub, so the machine opens no port. | One per worker. |
| Worker | Any machine with a node. The hub machine is usually a worker too. | As many as you like. |
| Claude session | One claude process doing one job: a lead, a writer, a reviewer. It uses your own ~/.claude setup. |
Many per node. |
| Desktop app | Where you chat with each project’s lead and see the fleet’s status. | Any number of devices. |
| CLI and MCP clients | fleetd commands, and agents such as Claude Code connected to <hub url>/mcp. |
Any number. |
The hub keeps its data in one SQLite file, ~/.fleetd/hub/hub.sqlite. See Config & files.
How work flows
Section titled “How work flows”- You open a project (a git repo on a worker) and write to its lead in the chat, such as
fix the typo in the README. - The lead plans the work: what to build, and what done looks like.
- The lead starts tasks. Each writer gets its own git worktree and branch, and opens a pull request.
- Reviewers check each pull request. The merge train merges it once CI passes on the exact commit.
- When the work is done, the lead closes it (
close) and says why. - The lead tells you in the chat.
When the lead needs a decision, it asks you in the chat. Typing while it works steers it.
The terms
Section titled “The terms”One per fleet. It holds projects, the lead chats, plans, tasks, decisions, the merge trains and checks. Start it
with fleetd init, which runs it as a service. It listens on port 4790 by default.
Node and worker
Section titled “Node and worker”Each worker runs one fleetd node. The node starts one claude process per live session, each writer in its own git
worktree. Sessions use your claude setup on that machine: the same login, proxy and MCP servers as claude in your
shell. See Machines.
Lead and its chat
Section titled “Lead and its chat”Each project has one lead: a long-running Claude session that plans the work and runs the agents. It never writes
code. You talk to it in one ongoing chat per project, in plain messages; it answers short, state first. Your first
message starts it. It runs on the high profile, claude-opus-5-5 unless you set another. See
Chat with the lead.
The lead keeps its own plan and bookkeeping. Inside fleetd a piece of work is a workstream; you never file one. Its tools are listed in Agent tools.
Decisions
Section titled “Decisions”A lead asks only about product calls, money and irreversible steps, in the chat, as numbered items with a
recommendation each. You reply tersely (1 go, 2 rec) or in your own words. The lead logs each answer with decide,
into a searchable decision log, so it never asks the same question twice. You can change a decision or revoke it, with
a short why (decisions_overturn); the lead reads that at its next wake, and asks again about a revoked one.
Secrets and approvals
Section titled “Secrets and approvals”Two things never travel as chat text. They show as items inside the chat:
| Item | Shows | You |
|---|---|---|
| Secret | A masked field: the machine and where the value goes | Type the value. It is sealed to that machine and never enters the transcript. |
| Approval | The exact command a lead wants to run, why, and where | Approve or Deny. |
See Secrets & approvals.
The agents strip
Section titled “The agents strip”Fleet activity stays quiet inside the chat: a compact strip under the lead’s message says how many agents are working, one line each, and expands to their lanes and time. Pull requests and merges show as one-line events.
Max agents
Section titled “Max agents”A per-project cap, and a fleet-wide one, on how many agents run at once. Agents over the cap queue rather than fail, and the lead plans its work to the cap. See Max agents.
Merge train
Section titled “Merge train”Only fleetd merges. Each repo has one train, a queue that rebases each ready pull request, waits for CI on that exact commit, and squash-merges it. Several ready PRs merge together in one CI run. See Merge train.
Every pull request merges on one clean review of its current commit plus green CI. A repo with no CI holds its PRs until it has some.
The lead closes work with close and one line on why. The reason is recorded, and the order’s agents still queued,
running or waiting for an answer are stopped, so none goes on, or starts later, for work that is over. The merge
train’s reviewers are left to the train. An agent whose machine is offline can’t be stopped yet: the lead hears which,
and stops it later. What counts as shipped is decided elsewhere: only the merge train merges, after green CI and
review.
What agents can call
Section titled “What agents can call”Leads and tasks act through fleetd’s MCP tools, never Claude’s own subagents. A lead starts agents with
spawn_agent; a task reports back with report and ask_lead.
- Agent tools: every tool an agent can call, generated from the code.
- What agents are told: every prompt fleetd sends a model.