Guide

How to Orchestrate Claude Code Agents Across a Software Project

Name: Fleet
Author: Fleet

Orchestration means more than launching agents. It means defining who does what, what triggers each agent, how they hand work to each other, and what happens when something goes wrong. Without orchestration you end up with agents stepping on each other or sitting idle waiting for input that never comes.

Fleet orchestrates Claude Code agents through a reactive event chain built on GitHub labels and a local event bus called Fabric. When a label changes, the right agent starts. When that agent finishes, it publishes an event that triggers the next agent. This guide walks through setting up that chain.

Before you start

Fleet installed and initialized in your repository (`fleet init`)
GitHub repository with label-based workflow (ready, needs-review, shipped)
GitHub CLI (`gh`) authenticated with write access to the repository
At least two agents defined in `.fleet/config.yaml`

1

Understand the reactive chain

Fleet's orchestration model is event-driven. A developer adds the ready label to a GitHub issue. The Fleet watcher detects the label, fires the assigned developer agent. The developer opens a PR and adds the needs-review label. The reviewer agent auto-starts, reviews the PR, publishes an approval event. The release manager merges. No manual hand-offs.

# The full chain in label terms:
# ready -> (developer starts)
# needs-review -> (reviewer starts)
# approved + mergeable -> (release-manager merges)
# shipped -> (ticket closed)

2

Define agent subscriptions in config

The subscribes_to field tells the watcher which fabric event triggers each agent. It takes a single event name or a list. A developer subscribes to ticket_ready, a reviewer to pr_needs_review, and so on.

agents:
  - name: backend-dev
    role: backend-developer
    department: engineering
    reports_to: tech-lead
    subscribes_to: ticket_ready
  - name: tech-lead
    role: tech-lead
    department: engineering
    subscribes_to: pr_needs_review
  - name: release-manager
    role: release-manager
    department: engineering
    subscribes_to: pr_approved

3

Start the watcher daemon

The watcher is the engine that watches for label changes and fires agents. Start it with --supervised to restart it automatically if it crashes. The watcher polls GitHub every two minutes and processes the Fabric event bus every ten seconds.

fleet watcher start --supervised

4

Dispatch a task to trigger the chain

Add the ready label to a GitHub issue and the watcher will pick it up within two minutes. You can also use fleet task assign to send a specific task description to a specific agent without going through labels.

# Via GitHub label (watcher-driven)
gh issue edit 42 --add-label ready

# Via direct task assignment
fleet task assign backend-dev "Implement pagination for /api/posts endpoint"

5

Monitor the orchestration flow

Use fleet log to see the decision trail. Every agent action — PR opened, review published, merge triggered — is recorded as a structured event. Use --type decision to filter to just the significant milestones.

fleet log --type decision
fleet log --agent tech-lead --since 24h

Common pitfalls

If the watcher is not running, label changes accumulate but no agents fire. Always verify `fleet watcher status` before assuming the chain is live.
An agent that exits without publishing a fabric event breaks the chain silently. Check `fleet log` when a stage seems stalled.
The `ready` label gate requires a `fleet` label on the issue by default in some configurations. Verify your label requirements match your GitHub label scheme.
Agent subscriptions use exact event name matching. A typo in the event name means the subscription never fires and there is no error message.

When Fleet is the right tool

Fleet orchestration makes sense when you have a repeatable multi-step workflow that currently requires human hand-offs between agents or between an agent and a person. If your workflow is one-shot (ask, get answer, done), orchestration adds complexity without value. Start with the reactive chain for the review-merge cycle before attempting more complex multi-stage pipelines.

Frequently asked questions

What happens if two agents try to pick up the same issue?

Fleet uses Fabric receipts to deduplicate event delivery. Once one agent claims a `ticket_ready` event, the same event is not dispatched to another agent. The dedup window for work-in-progress labels is 15 minutes.

Can I orchestrate agents across multiple repositories?

Yes. Org-level agents defined in `~/.fleet/org.yaml` subscribe to events from all repositories. Repo-level agents are scoped to their repository. You can mix both tiers in one workflow.

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