What is the difference between an org agent and a repo agent?

Org agents live in `~/.fleet/org.yaml`, use the `__org__` project sentinel, and see fabric events from all repositories — they suit cross-cutting roles like CTO or product lead. Repo agents live in a repository's `.fleet/config.yaml` and are scoped to that single repo.

How does an event in one repo reach agents watching another?

Through Fabric, the shared event bus across both tiers. A repo agent publishes an event (such as `ticket_shipped`) to fabric, and the org watcher — which sees events from every repo — fires any org agent subscribed to that event.

Do I need a separate watcher for each repository?

Yes for repo agents: run `fleet watcher start` inside each repository. For cross-repo visibility, also run one org watcher with `fleet watcher start --org`, which drives the agents defined in `~/.fleet/org.yaml`.

Can the same agent name exist in two repositories?

Yes. Agent names are unique per repository, scoped by the `repo` field in config, so a name like `tech-lead` can exist independently in each repo. Org agents are distinguished internally by the `__org__` sentinel.

How to Coordinate AI Agents Across Multiple Repositories with Fleet

Name: Fleet
Author: Fleet

A single repository is the easy case. Real organizations run several repos — a backend service, a frontend app, an infrastructure repo — and the work in one constantly affects the others. A reviewer in the backend repo has no idea a PR just shipped in the frontend, and a CTO-level agent that should see everything is stuck watching one repo at a time.

Fleet is org-centric by design. It runs two tiers of agents: org agents that see fabric events from every repository, and repo agents scoped to a single repository. Both tiers publish to and subscribe from the same shared event bus — Fabric — so an event raised in repo A can surface to an org agent and influence what happens in repo B. This guide shows how to set up both tiers and trace an event from one repo to the org layer.

Before you start

Fleet installed (`curl -fsSL https://fleetctl.ai/install | sh`)
Two or more GitHub repositories you want agents to operate across
An `~/.fleet/org.yaml` file for org-level agents (CEO, CPO, CTO, PMs)
A `.fleet/config.yaml` in each repository for repo-scoped agents
GitHub CLI (`gh`) authenticated with access to all the repositories

Understand the two tiers

Fleet separates agents into org agents and repo agents. Org agents live in ~/.fleet/org.yaml and represent cross-cutting roles — a CTO, a CPO, product managers — that need visibility across the whole org. They use the internal project sentinel __org__ and see fabric events from ALL repositories. Repo agents live in each repository's .fleet/config.yaml and are scoped to that one repo: developers, reviewers, and release managers that act only on their own repository.

# Org agents (cross-repo visibility):
#   ~/.fleet/org.yaml      -> project sentinel __org__
#
# Repo agents (single-repo scope):
#   <repo>/.fleet/config.yaml

Define org agents in org.yaml

Create ~/.fleet/org.yaml with the cross-cutting roles. Org agents are not tied to one repository, so they are the right home for leadership and product roles that need to react to activity anywhere. Each agent uses the same per-agent fields as repo agents — name, role, model, subscribes_to — and the org watcher runs them against the org-wide event stream.

# ~/.fleet/org.yaml
agents:
  - name: cto
    role: tech-lead
    department: engineering
    model: claude-opus-4-5
    subscribes_to: ticket_shipped
  - name: product-lead
    role: tech-lead
    department: product
    model: claude-sonnet-4-5
    subscribes_to: ticket_shipped

Define repo agents in each repository

In every repository, add a .fleet/config.yaml with the agents that work on that repo. These are your developers, reviewers, and release managers. They are scoped to their repository and only see events from it. Set repo: and owner: so Fleet knows which GitHub repository this config drives.

# backend-repo/.fleet/config.yaml
repo: your-org/backend
owner: your-github-username
product_name: Backend API
required_label: fleet

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

Start a repo watcher for each repository

Each repository runs its own repo watcher, started from inside that repo. The repo watcher handles that repository's label polling and fires its repo-scoped agents. Run one per repository you want active.

# In the backend repo:
cd /path/to/backend
fleet watcher start --supervised

# In the frontend repo (separate watcher):
cd /path/to/frontend
fleet watcher start --supervised

Start the org watcher

The org watcher is what gives org agents their cross-repo visibility. Start it with the --org flag. It runs the agents defined in ~/.fleet/org.yaml against the shared fabric event stream, so they react to events originating in any repository — not just one.

# Start the org-level watcher:
fleet watcher start --org

# Check it is running:
fleet watcher status --org

Trace an event from repo A to the org tier

Fabric is the shared event bus across both tiers — this is what makes cross-repo coordination work. When a release manager in the backend repo merges a PR and publishes ticket_shipped, that event lands on the shared bus. The org watcher's matcher sees it (org agents subscribe to events from all repos) and fires any org agent subscribed to ticket_shipped — for example the CTO agent, which now knows backend shipped without ever watching the backend repo directly.

# In backend repo: release-manager publishes on merge
# (the /fleet-ship-pr skill does this automatically):
fleet fabric publish --kind ticket_shipped --sender release-manager \
  --summary "Shipped #128 in backend" --payload '{"repo":"backend","issue":128}'

# The org-tier CTO agent, subscribed to ticket_shipped, reacts.
# Confirm the cross-repo flow in the unified log:
fleet log --type decision --since 1h

Common pitfalls

Org agents only get cross-repo visibility when the org watcher is running. If you start repo watchers but forget `fleet watcher start --org`, repo agents work fine but nothing at the org tier ever fires. Verify with `fleet watcher status --org`.
Each repository needs its own repo watcher. A single repo watcher does not poll multiple repositories — start one per repo you want active, from inside that repo.
Agent names are unique per repository (scoped by the `repo` field), so the same name can exist in two repos without colliding. Org agents use the `__org__` sentinel internally. When reading a cross-repo log, identify agents by repo plus name, not name alone.
Fabric is shared, so a poorly scoped subscription on an org agent can fire it on noisy events from every repo at once. Subscribe org agents to coarse milestone events like `ticket_shipped` rather than high-frequency events like `pr_created` unless you really want org-tier reaction to every PR.
An event only reaches the org tier if it is actually published to fabric. If a repo agent finishes work but exits without publishing its fabric event, the org watcher has nothing to react to. Check `fleet log` for the missing decision event when a cross-repo hand-off does not happen.

When Fleet is the right tool

Fleet's two-tier model is the right fit when you run several repositories and need agents that react to the whole picture — a CTO-level agent that sees every ship, a product agent that tracks delivery across services — while keeping per-repo developers and reviewers tightly scoped. Fabric as a shared bus means you get that cross-repo awareness without standing up any message-queue infrastructure.

It is overkill for a single repository. If everything you build lives in one repo, skip the org tier entirely and run only repo agents — the org layer earns its keep specifically when work in one repo needs to be visible to agents that span all of them.