Orchestration
Running agents across many repos raises a question that one repo never does: where does the plan live? One ready-made answer is Fleet , an orchestrator that runs its agent sessions in Thurbox. This page starts there, then walks through the Thurbox primitives it is built from, for when you want to drive them yourself.
Fleet: one session per Task #
Fleet is a standalone program, not a Thurbox extension. A Task is a resource that names a harness (the agent), a host, a workspace and a brief. Fleet starts one Thurbox session for it, sends the brief once, records the result the worker reports, and releases the session when you delete the Task.
- Resources, not chat. Tasks, the ChangeRequests they declare, and the configuration they run with are stored as versioned resources on disk, so the plan outlives every session.
- Isolated workers. A Task's workspace is a directory, or one or more repositories, each on its own git worktree.
-
A reconcile loop.
fleet upkeeps every Task moving until you stop it, and starts VEGA, the bundled lead workspace. - Forge follow-through. A ChangeRequest mirrors one pull or merge request on GitHub, GitLab, Azure DevOps or Bitbucket.
Install
Fleet ships one binary for Linux, x86_64 and aarch64; it has no Windows or macOS release. To run
real sessions it needs Thurbox with
thurbox-cli
on
PATH
, and an agent CLI that is installed and logged in (the VEGA starter uses Codex).
curl -fsSL https://github.com/Thurbeen/fleet/releases/latest/download/install-release.sh | sh
fleet init # the config and the VEGA workspace, offline
fleet up # the manager; keep it running in its own terminal
Fleet's
README
covers setup, updates and uninstalling, and its
initialization guide
covers the config, the workspace and
fleet up
.
Fleet Lens, in Thurbox
Fleet Lens
is the Thurbox pane for Fleet: a read-only float that lists every resource kind Fleet serves,
Tasks first, with the ones that need a person on top.
Alt+K
opens it,
Enter
reads a resource as YAML, and
Tab
steps through the kinds. It reads Fleet only through
fleet … --json
and writes nothing.
thurbox-cli plugin install git+https://github.com/Thurbeen/thurbox-fleetlens
thurbox-cli plugin check
It needs Thurbox 2.76.2 or later. Then trust it, because it runs
fleet
: Settings (
Ctrl+,
), then
]
, select
thurbox-fleetlens/plugins/88_fleet_lens.lua
and press
t
. Its
README
lists its keys, columns and settings.
How Fleet runs a Task #
fleet apply ─▶ spawn session ─▶ send brief ─▶ worker runs
│ fleet result
fleet delete ─▶ release session ◀── Concluded ◀───┘
While
fleet up
runs, you drive Tasks with the CLI:
| Command | What it does |
|---|---|
fleet apply -f task.json |
Creates or updates a Task; dispatch: true lets it start |
fleet list task · fleet status task <name> |
Every Task and its phase; one Task's conditions: Spawned, Briefed, Concluded |
fleet send <name> <text> |
Messages the running session |
fleet result <name> --generation N --outcome … |
The worker's own report; only that concludes a Task |
fleet delete task <name> |
Releases the session, then removes the Task |
fleet up
holds one manager lease and sweeps once a second by default. Ctrl-C releases the lease and keeps
the sessions, so a restarted
fleet up
reconnects to them. Fleet passes no credentials to a session: they stay with the agent and its
host.
Fleet v1, the Python control plane that installed itself as a Thurbox extension, is frozen
at
v1.0.0
. Fleet v2 does not read its data; the README's
v1 section
says how to keep or leave it.
Start by just asking #
Before any of the structure below: you do not have to write the orchestration yourself.
thurbox-cli
is installed beside
thurbox
, so it is already on every session agent’s
PATH
— from inside any session you can ask for a fleet in English.
-
Using
thurbox-cli, start refactor sessions for this repo — one per crate, each on its own worktree branch offmain, and send each one a prompt to refactor its crate. Then show methurbox-cli session list. - Spawn a reviewer session on this repo with no worktree, and send it standing instructions to review every file I change.
-
Create a nightly automation that sends “triage new issues” to the
triagesession on weekdays at 09:00.
The agent discovers the surface with
thurbox-cli --help
; the commands it reaches for are
session create
(with
--worktree-branch
,
--agent
,
--host
,
--add-repo
),
session send
,
session list
and
automation create
. Everything it does shows up in your running TUI within a tick, because the TUI and the CLI
share one SQLite database. The
recipes
page has the same thing written as bash, if you would rather commit a script.
That covers a handful of sessions on one goal. The rest of this page is about what changes when you are doing it across many repos, repeatedly.
The problem #
One repo, one agent session, one task: nothing to orchestrate. The repo holds the code, the session holds the context, and the pull request is the record of what happened.
At five repos this breaks in a specific place. The work still lands in the repos — that part is fine. But the plan has nowhere to live. A goal that spans three repos is not a file in any of them. Neither is the context that makes the goal legible: what each project is for, which ones depend on each other, which are dormant. Neither is the log of what you launched last Tuesday and what came back.
So it ends up in a chat transcript — not durable, not diffable, and not readable by the next session.
The control plane #
Give the plan its own repo, holding two things and nothing else:
- The map. An always-current index of your repos, generated from your forge accounts so it cannot drift, plus hand-written context files holding the judgement a generated index can't: what a project is for , how it relates to the others, what its current goals are.
- The orchestration. A task queue, reusable recipes (playbooks) and one log per run.
The defining rule is what the control plane does not hold:
The control plane holds the plan and the log . It never holds the workers' branches.
Each unit of work becomes one Thurbox worker session, targeting a real repo in its own git worktree , driven by a single self-contained prompt. Workers share no context with the control plane and none with each other, so every prompt restates the goal, the constraints, and what "done" means, from scratch.
Why split generated from hand-written? They have different failure modes. An index of repo names and default branches goes stale the moment you rename something, so it must be regenerated and never hand-edited. Why a project exists cannot be generated at all, and changes on a human timescale. One file for both guarantees that refreshing the half that must be fresh destroys the half that must be preserved.
Why a separate repo? The plan outlives every branch it spawns. A run log inside a worker repo would collide with the branches it describes, and would need a new home the moment a run touched a second repo. The split also makes the rule enforceable rather than aspirational: a control plane with no worktrees cannot accidentally become a place where work happens.
The run loop, in Thurbox calls #
Fleet is built on the same
thurbox-cli
you have: it creates, reads, messages and deletes sessions by a stable
--key
. If you build a lead of your own, these are the calls to reach for:
# Spawn a worker: its own worktree, parented to the lead.
thurbox-cli session create \
--name ship-auth-fix \
--repo-path /abs/path/to/repo \
--worktree-branch fix/auth --base-branch main \
--parent "$THURBOX_SESSION" \
--json
# Follow every transition as it happens. No sampling, no polling loop.
thurbox-cli watch --json --initial
# Enumerate the run's workers — including the silent ones.
thurbox-cli session list --parent "$LEAD" --json
# A replacement lead adopts a worker.
thurbox-cli session reparent "$WORKER" "$NEW_LEAD"
A Fleet worker finishes by running
fleet result
with an outcome and a summary, recorded on its Task. Only that concludes the Task.
Why it is a Thurbox pattern #
Nothing above is invented. Each piece is a Thurbox primitive doing load-bearing work.
Worktree-per-session
A worker creates a git worktree on its own branch. Two workers on the same repo cannot collide, and an abandoned worker costs you a directory, not a dirty checkout on a branch someone else needs. This is what makes "one unit of work, one session" safe to say.
The lead is a real session
A lead you build yourself can install itself as an
extension
with one long-lived
[[sessions]]
entry, which Thurbox
self-heals
: delete the session and it comes back at the next startup or automation tick. A control plane
that evaporates when someone tidies their session list is not a control plane.
And because it
is
a real session rather than an ad-hoc terminal, it can be addressed: workers can mail it, it has a
UUID to hand out as
--parent
, and it gets
THURBOX_SESSION
in its environment like any other session.
A reported result, not a poll
A Fleet worker reports by running
fleet result
, which records its outcome and summary on the Task, and declares any pull or merge request it
opened as a ChangeRequest that Fleet follows on the forge. A turn ending is not a task finishing,
so nothing else concludes a Task.
Why not poll
gh pr list
?
A report the worker makes on purpose is
exact
(it comes from a worker that knows it finished, not from a side effect), it is
durable
(it survives the lead session restarting), and it can say
"not applicable"
. A worker that correctly concludes there was nothing to do says so in its result. A PR poll
cannot distinguish "no PR because nothing needed fixing" from "no PR because the worker is still
thinking" — and those demand opposite responses from the lead.
Thurbox's
inter-session messages
are there for a lead you build yourself: a worker can mail its lead, and
--no-wake
leaves a note without typing into the lead's terminal.
A supervised loop, not automations
Fleet's periodic work is not a Thurbox
automation
. It is
fleet up
: one manager holding a lease, run in a terminal or under your own service supervisor, and
stopped only by you. It sweeps on a timer, because a worker that died on a token limit fires no
hook to say so.
Restraint is still part of the pattern. A session Fleet cannot observe is never blindly replaced, and a stalled Task waits for a person to inspect it.
Three constraints #
Each costs real time to rediscover.
The status field is not a completion signal
session get
/
list --json
do
carry the
working
/
blocked
/
done
/
idle
state that
agent hooks
report via
session signal
, in
hook_state
. What they cannot carry is any guarantee that it is
current
: the value is latched — whatever was written last, by an agent that may since have
crashed, been interrupted, or never have been wired to report at all. Polling it for completion
is how a lead waits forever on a worker that finished an hour ago.
So headless completion detection is something the worker reports on purpose — a result
command such as
fleet result
, a result file, a mailbox message, or a printed sentinel the lead greps out
of
session capture
. What the state fields are for is
supervision
— noticing that a worker is stuck, blocked or gone — and each arrives with what it
takes to judge it:
hook_state_age_secs
(how old the report is; there is deliberately no built-in staleness timeout, since a turn may
legitimately run for an hour),
hook_reported
(whether anything ever reported — silence is not
idle
),
hook_coverage
(what this agent can report at all), and
hook_corroboration
/
hook_state_contradicted
(what actually holds the pane, and whether it agrees).
thurbox-cli session doctor
turns the same picture into a verdict and an exit code.
And a session whose agent Thurbox did not launch is no longer invisible: its pane is read, so a
known agent binary in the foreground reports
state: "running"
with
state_source: "process"
. Better still, have your harness call
session signal
itself —
THURBOX_SESSION
is already in the pane's environment, so the call needs no arguments. To get the real hooks
rather than the coarse pane reading, ask for the wiring:
thurbox-cli agent launch-args <name>
prints the
command
,
args
and
env
Thurbox itself would launch with — the status hooks
are
arguments, so an agent started any other way has none.
A session parked with
session stop
is equally readable:
stopped: true
and
state: "stopped"
on
session get
and
list
alike, so a liveness check is the poll you were already doing. Parking also
clears the latched state and refuses a new one — a parked session has no
process, so a heartbeat poll or a mirror pass writing a turn onto it would
report something that did not happen.
watch, for everything that is not a report
A result file is how a worker says it finished.
thurbox-cli watch --json --initial
is how a driver learns everything the worker was never going to mail: that it
went blocked on a permission, that its pane died, that somebody deleted it.
It streams an
append-only log
, not a sampled diff. Every writer that changes what a watcher reports appends
its event in the same transaction as the change, so two transitions in the
same instant are two events — which matters because
working → blocked → working
is exactly what an auto-answered permission looks like, and a sampler reading
the row every 250 ms sees neither edge. Each line carries a monotonic
seq
(
--since <seq>
resumes exactly where a restarted driver left off), a
reason
saying which kind of event it was —
soft_deleted
can be restored,
force_deleted
cannot, and
lost
is a pane that died with nobody asking, such as a multiplexer crash — the
from_state
→
to_state
of the transition, and the same gating fields
session get
publishes, so acting on a
blocked
needs no second call. The stream exits the moment its reader closes the pipe.
Read the exit status before parsing
Errors are structured documents on
stdout
, not lines on stderr — an agent reads one stream. The exit code carries the verdict (
0
ok,
1
ran and failed,
2
bad invocation,
3
a session reference matched more than one session), and the trap that follows is worth naming:
thurbox-cli … --json | jq -r '.field'
exits
0 with empty output
when the command failed, because
jq
parsed the error object and the pipeline carries
jq
's status.
set -o pipefail
does not help. Capture first, branch on the status, then parse.
out=$(thurbox-cli session get "$ref" --json) || {
printf 'thurbox: %s\n' "$(jq -r .error <<<"$out")" >&2
exit 1
}
id=$(jq -r .id <<<"$out")Fast-forward the base branch first
A worktree inherits whatever the
local
base branch points at, not what the remote does. A stale local
main
yields a worker that does perfectly correct work against a month-old tree and opens a conflicting
PR — a failure that looks like a bad agent and is really a bad base.
git -C "$REPO" fetch origin
git -C "$REPO" merge --ff-only origin/main
git -C "$REPO" rev-list --count main..origin/main # expect 0Building your own lead #
Fleet is a separate program: nothing in Thurbox knows it exists. If you would rather build a lead as an extension , two choices are worth copying because they follow from how extensions work, not from taste.
The lead's job description is a payload file, not a prompt.
A
[[files]]
entry lays it down in the extension home, and
[[symlinks]]
surface it as
CLAUDE.md
,
AGENTS.md
and
GEMINI.md
, so the lead reads what it is
for
whichever CLI is behind it. Keep that text apart from the repo's own
AGENTS.md
: one says what the session is for — hold the plan and the log, never the branches —
and the other says how to work inside the checkout. A lead whose invariant lives only in the
conversation that stated it keeps that invariant exactly as long as the conversation.
A manifest that names your clone has to be rendered.
[[sessions]] repo_path
may need to name a checkout, and
{home}
resolves to the extension home, not to it. A committed file cannot hardcode a path that exists on
one machine, so ship the manifest as a template with a placeholder, and have your installer
render it with the clone's absolute path before running
thurbox-cli extension install
.