Guide

How to Scale from a Single AI Agent to a Full Fleet

Name: Fleet
Author: Fleet

Most teams start with one AI coding agent and a single task. That works until the tasks pile up or the single agent becomes the bottleneck on a workflow that could move in parallel. Scaling to a fleet is not about adding agents indiscriminately — it is about identifying where serialization is costing you and adding agents to remove those specific constraints.

This guide describes a practical progression from one agent to a structured multi-agent fleet, with decision criteria at each step so you add complexity only when it earns its keep.

Before you start

At least one Fleet agent running successfully on real tasks
A clear picture of where your current workflow is serialized unnecessarily
Fleet initialized in your repository with a working `.fleet/config.yaml`

1

Start with one agent and observe

Before adding agents, run a single developer agent on your highest-priority tasks for a week. Measure how long tasks take end-to-end and where the agent spends most of its time. This baseline tells you where parallelism will actually help.

# Single-agent baseline setup:
agents:
  - name: dev-1
    role: backend-developer
    model: claude-sonnet-4-5

# After a week, review:
fleet log --agent dev-1 --since 7d

2

Add a reviewer agent when PRs stack up

The first scale-up that consistently pays off is adding a reviewer agent. If your developer is opening PRs but they sit unreviewed for hours while the developer sits idle, add a tech-lead reviewer that auto-starts on PR creation. This removes the most common bottleneck.

agents:
  - name: dev-1
    role: backend-developer
    model: claude-sonnet-4-5
    subscribes_to: ticket_ready
  - name: tech-lead
    role: tech-lead
    model: claude-opus-4-5
    subscribes_to: pr_needs_review

3

Add a second developer when work streams diverge

If you have two genuinely independent features in flight at the same time and a single developer agent is serializing them, add a second developer. Use git worktrees to give each developer its own isolated checkout. Assign tasks explicitly with fleet task assign.

# Add a second developer and worktree:
git worktree add ../repo-feature2 feature/new-task

agents:
  - name: dev-1
    role: backend-developer
    worktree: /path/to/repo-feature1
  - name: dev-2
    role: frontend-developer
    worktree: /path/to/repo-feature2

4

Add a release manager when merges are manual

If you are manually merging PRs after the reviewer approves, add a release manager agent. It subscribes to pr_approved, runs the release gate check, and merges mergeable PRs automatically. This closes the loop from ticket to shipped without human involvement.

agents:
  - name: release-manager
    role: release-manager
    model: claude-sonnet-4-5
    subscribes_to: pr_approved

5

Add QA when quality issues escape review

A QA agent is worth adding if your reviewer is missing regressions or you want automated test runs before merge. The QA agent subscribes to pr_created or pr_approved, runs your test suite, and publishes the result. Add it at this stage, not earlier — wait for a real quality gap before adding the complexity.

agents:
  - name: qa-agent
    role: qa-engineer
    model: claude-sonnet-4-5
    subscribes_to: pr_approved

6

Verify the full chain before expanding further

After each agent addition, run fleet log --type decision for a few days and verify the chain is flowing correctly. Each new agent should reduce a measurable bottleneck. If adding an agent does not improve throughput or quality, do not add the next one yet.

fleet status
fleet log --type decision --since 72h

Common pitfalls

Adding agents before you have a working single-agent setup amplifies problems instead of solving them. Fix the one-agent case before scaling.
More agents mean more potential for event loops and dedup edge cases. Keep your team size at the minimum needed to remove real bottlenecks — 4 to 6 agents is a common working set for most projects.
Each new agent adds to your monthly API cost. Track cost per agent using `fleet agent budget` and make sure each agent is earning its keep through throughput improvement.
Agents that sit idle most of the time (no events triggering them) are not a problem in terms of cost (idle sessions consume no tokens), but they add config complexity. Remove agents you are not using.

When Fleet is the right tool

Scaling to a fleet is the right move when you can identify a specific stage in your workflow that is creating a queue of waiting work and where that stage can be automated. It is the wrong move if your primary bottleneck is the quality of requirements, architectural uncertainty, or unavailability of human reviewers for judgment calls that AI cannot make.

Frequently asked questions

Is there a recommended fleet size for a solo developer?

3 agents is a practical starting point for a solo developer: one developer, one reviewer, one release manager. This covers the full ticket-to-merge cycle without over-engineering.

How do I know if I have too many agents?

If agents are consistently idle (no triggering events) or if your API costs are growing faster than your output, you may have over-staffed the fleet. Check `fleet agent budget` and trim roles that are not being triggered regularly.

Run your first agent fleet

One binary. Five minutes. See every agent, coordinate every handoff, and keep a full audit trail of what your fleet did.

See how it works Install Fleet