Agent Fleets

stella fleet runs many tasks at once. Each task gets its own full stella worker. By default, all the workers share one tree: every worker runs in the repository root, coordinated by cooperative file claims. If two workers try to touch the same file, the conflict shows up right away and names which worker is holding it. Commits from different workers interleave on one branch, and the build cache stays warm. A task marked isolation = "isolated" instead gets its own git worktree on its own branch, kept separate from your working copy and from every other worker.

stella fleet \
  "Add unit tests for the parser module" \
  "Document every public function in src/api/" \
  "Fix the clippy warnings in the store crate"

How a fleet run works

1. Plan. Task prompts, whether typed inline or loaded from a --plan file, form a dependency graph: tasks with depends_on wait for their dependencies to finish first. Plans are checked before anything runs. A duplicate id, a task that depends on itself, an unknown dependency, or a dependency cycle gets rejected, and stella names the task or cycle that caused it.

2. Share or isolate. By default, every worker runs directly in the repository root, using the cooperative file claims described below. A task marked isolation = "isolated" instead gets a fresh git worktree under .stella/worktrees/<slug>, branched from a pinned base commit. That base is the current HEAD or --base-ref, locked to a specific commit at the start of the run so later commits can't shift it. The worktree lands on a fleet/<slug>-<hash> branch. The 16-character hash keeps re-runs, which reuse task ids like t1, from colliding with branches and worktrees left over from an earlier fleet. Isolated workers can't see each other's uncommitted work and can't touch your checkout.

3. Dispatch in waves. Tasks run in dependency order, in waves of up to --max-concurrency tasks at once. The default is the governor's number. A failed task does not unblock the tasks waiting on it; those end the run marked skipped. Nothing retries on its own. The ledger records every attempt, but re-running is up to you.

4. Work. Each worker runs the full engine: the plain step loop by default, with the standard set of tools, following your agent-engine config. Workers run headless on purpose: no MCP, no interactive prompts, nothing that can get stuck waiting for input. Pass --pipeline <variant> to route each worker through an installed wrapper plugin instead.

5. Record. Every attempt, commit, and dollar spent lands in the fleet ledger at .stella/private/fleet.db. Like all stella telemetry, it's a local SQLite database, with runs, tasks, attempts, and commits tables you can query directly. Past runs also show up on the Fleet runs card of the Observatory dashboard.

   copy

   # Which tasks failed in the most recent run, and what the worker said.
   sqlite3 .stella/private/fleet.db \
     "SELECT a.task_id, a.branch, a.summary
        FROM attempts a
       WHERE a.run_id = (SELECT id FROM runs ORDER BY created_at_ms DESC LIMIT 1)
         AND a.success = 0;"

   In the shared tree, the commits table records the commits each worker was observed making. While a worker commits, it holds a workspace-wide commit lane, so no other worker can move HEAD during that window. Each commit belongs to exactly one task. If a commit happens some other way in the shared tree, for example through the shell (which is off by default), it's left out of the table rather than guessed at. An isolated task has only one writer in its own worktree, so every commit it makes gets recorded, no matter how it was made.

6. Review. Shared-tree work lands directly on your current branch as interleaved commits. Isolated tasks' worktrees and fleet/* branches stay in place on purpose; those branches are the actual work product. Inspect, test, and merge them whenever you're ready. git worktree list shows all of them.

Plan files

For anything beyond a handful of independent prompts, declare a plan (.toml or .json):

[[tasks]]
id = "t1"
title = "Bump the version and changelog"
prompt = "Bump the workspace version to 1.4.0 and update CHANGELOG.md"
claims = ["Cargo.toml", "CHANGELOG.md"]

[[tasks]]
id = "t2"
title = "Update the release notes page"
prompt = "Update the release notes for 1.4.0 from the merged PRs"
depends_on = ["t1"]

The task fields the plan parser accepts:

This plan uses all of it: three waves, one isolated task, and claims that keep the parallel writers apart. Claims match as exact strings, so name individual files, not directories:

[[tasks]]
id = "schema"
title = "Add the migration"
prompt = "Add a migration creating the `receipts` table with an execution_id foreign key"
claims = ["src/store/schema.rs", "src/store/migrations.rs"]

[[tasks]]
id = "reader"
title = "Read path"
prompt = "Add Store::receipts_for_execution reading the new receipts table"
depends_on = ["schema"]
claims = ["src/store/read.rs"]

[[tasks]]
id = "writer"
title = "Write path"
prompt = "Record one receipt row per model call from the engine's emit path"
depends_on = ["schema"]
claims = ["src/store/write.rs"]

[[tasks]]
id = "docs"
title = "Rewrite the receipts page"
prompt = "Rewrite docs/receipts.md against the new table; try two structures and keep the better one"
depends_on = ["reader", "writer"]
isolation = "isolated"

stella --spend-limit 6 fleet --plan feature-buildout.toml

schema runs alone in wave one. reader and writer run together in wave two, each with its own claims so they don't overlap. docs runs last, in wave three, in its own worktree on its own fleet/docs-<hash> branch, since it's divergent work that needs isolation rather than claims. If reader and writer had both claimed src/store/schema.rs, the second one to dispatch would have failed by name instead of racing the first.

File claims — cooperative locks

A task that declares claims (paths it plans to touch, relative to the workspace) holds those paths as file locks for as long as the attempt runs. If a second task, or even a second fleet run, tries to claim a path that's already held, that dispatch fails by name instead of silently racing another worker for the same file. The locks live in the file_locks table of .stella/private/store.db, separate from the fleet ledger, so they coordinate across fleet runs happening at the same time too.

Spend limit across a fleet

The spend limit comes from the global --spend-limit flag (or STELLA_SPEND_LIMIT), which goes before the subcommand:

stella --spend-limit 5 fleet --plan release-prep.toml
# equivalently: STELLA_SPEND_LIMIT=5 stella fleet --plan release-prep.toml

It's enforced in two ways. Each worker runs under its own guard, which is the total cap divided by the concurrency width (spend limit ÷ max-concurrency), so one wave's workers can't collectively spend more than their share. On top of that, the fleet stops launching new waves once total spend crosses the cap. Workers already running are allowed to finish cleanly; stella never kills one mid-task.

Watch CI: --watch

After the fan-out finishes, --watch keeps an eye on every branch that has successful work on it. It watches each branch's CI run through to completion using the gh CLI, keeps PR status updated live, and exits with a non-zero code if any watched branch ends up red. It checks every 30 seconds, gives CI 10 minutes to start showing up, gives up on a branch after 20 minutes with no progress, and stops watching entirely after 2 hours.

stella fleet --plan release-prep.toml --max-concurrency 2 --watch

Flags

The spend-limit flag is global, so it goes before the subcommand. This is the one ordering mistake worth remembering:

stella --spend-limit 8 fleet --plan release-prep.toml --max-concurrency 3 --watch

Clean up

Once you've merged, or rejected, the branches your isolated tasks left behind, clean them up. The branch names carry a hash suffix, so list them instead of guessing:

git worktree list                  # what the fleet left in .stella/worktrees/
git worktree remove <path>         # per worktree
git branch --list 'fleet/*'        # the fleet branches
git branch -D fleet/<slug>-<hash>  # per branch, exactly as listed

Once every branch is merged or rejected, this sweeps them all in two lines:

git worktree list --porcelain | awk '/^worktree .*\.stella\/worktrees\//{print $2}' \
  | xargs -r -n1 git worktree remove
git branch --list 'fleet/*' --format='%(refname:short)' | xargs -r git branch -D

Next