Guides

How to think about agent coordination

Six guides on one page — mechanics first, slogans never. Jump to a topic or read straight through.

• Fleet coordination
• Exclusive leases
• Territory maps
• Monorepos
• CI fleets
• Scaling fleets

Fleet coordination

One agent on one branch is a demo. Ten agents across laptop, CI, and cloud on the same codebase is production. Coordination means shared state before edit: who intends to touch which paths, who already holds them, and what happens when two claims overlap.

Without that layer, agents open overlapping PRs, burn reviewer time, and treat merge conflicts as noise. With it, the fleet becomes an air-traffic system — claim work, wait when blocked, take another path when free. The control plane is the shared referee; Git remains the history store.

Practical starting point: wrap agent invocations with managent run, keep one API URL and org key for the fleet, and watch residual conflict rate after you turn coordination on — not agent count. See the manifesto for the thesis, or the live demo for the behavior.

Exclusive leases

A lease is a time-bounded claim on files, globs, or inclusive line ranges. The agent acquires before writing, heartbeats while the process runs, and releases on exit — including failure paths. Overlap checks reject incompatible grants; idempotency keys keep retries from double-booking territory.

Hotspot directories can split into short-TTL child leases so one busy package does not freeze an entire tree. The CLI tracks every id, heartbeats each, and releases the set together. Integrators that bypass the CLI must do the same — orphan leases from SIGKILL hold until TTL unless transferred.

Leases turn vibes into a contract. Laptop sessions, CI jobs, and cloud runners speak the same protocol. Within respected leases, exclusive claims do not overlap. Agents that ignore leases need advisory drift detection, optional hardened runtime, and PR verify — not louder slogans. Deeper writeup: Exclusive leases.

Territory maps

The territory map is the live view of ownership. Hot paths light up under lease; idle regions stay open. Platform engineers can answer “who is touching auth right now?” without grepping logs or guessing from open PRs. Queue depth and hotspot flags make contention visible before it becomes a merge-queue tax.

Maps beat merge queues for the same reason lock tables beat hoping for serializability: you see contention before you pay for wasted work. managent status and managent watch read the same /map endpoint as the dashboard. Read Introducing the Territory Map.

Monorepos

Monorepos amplify collision surface. Shared packages, generated code, and hot directories attract every agent at once. Coordination here is not optional — it is how you keep parallel agent spend productive instead of thrashing the same package graph overnight.

Practical pattern: lease at the package or directory boundary your agents already think in; exclude generated paths when safe; require verify-on-PR so local bypasses cannot land. Prefer directory leases for partition plans; line ranges are for ad-hoc precision, not for pretending the whole monorepo is fine-grained forever.

More on the monorepo solution page. For the empirical collision baseline that motivates this, see research.

CI fleets

CI agents are short-lived, high-concurrency, and easy to forget in a laptop-centric mental model. They still need identity, leases, and release-on-exit — otherwise a burst of PR jobs will claim the same hot paths as human-driven sessions and leave orphan territory when runners die hard.

Wire managent run around the agent step; pass MANAGENT_AGENT_INSTANCE_KEY for ephemeral runners so identity does not churn on hostname; keep API keys in CI secrets, never in the client bundle. The acquire-lease GitHub Action can install hard_fail hooks on the runner — still bypassable with --no-verify, so require the PR gate. See CI fleets.

Scaling fleets

Scale is not “more agents.” It is more concurrent writers without linear growth in conflicts. Measure residual conflict rate, lease wait time, queue depth, and verification outcomes (pairs_checked, root causes). Partition work when hotspots dominate; keep humans on policy and review.

Start with advisory coordination, add hardened runtime where threat models require it, and always close the loop with PR checks. Polyrepos still share an org control plane — lease per repo, watch contention where services meet. Security posture: /security. CLI concepts: /docs.