How coordination works

AgentCollision starts by blocking a second writer: when two chats reach for the same file, the later one is denied before its edit lands. That stops the clash — but the two agents could go further and just sort it out: reach out, agree who goes first, hand off the file. That's coordination, and how far it goes is entirely up to you.

The one knob: autonomy_level

Rather than wire up half a dozen switches, you set one value and AgentCollision maps it onto the individual behaviors.

• manual — detection only. Collisions are blocked and recorded; you handle every handoff by hand. Nothing is sent to a peer automatically.
• assist — agents flag, you confirm. A blocked agent messages the holder and opens a negotiation, but the actual handoff waits for a human.
• auto — end-to-end. The daemons broker an idle holder's lease and release it automatically; the blocked agent just proceeds.

Set it interactively — this walks you through solo / small-team / compliance presets and writes the config for you:

agc arc-claim policy

Or set it directly in ~/.agentcollision/claims_policy.yaml:

session:
  autonomy_level: assist   # manual | assist | auto

Reach-out: a heads-up on conflict

At assist and above, when your edit is denied because a peer holds the file, your daemon automatically messages the holder — “I need src/auth.ts, you're holding it; can you wrap up?” — instead of you noticing the denial and pinging by hand. It's deduped per (you, holder, file) on a cooldown (default 5 minutes), so nobody gets spammed about the same file.

Negotiation: brokering the handoff

Reach-out is a heads-up. Negotiation is the brokered exchange that can actually free the file. When you hit a held file, your daemon opens a negotiation proposing an outcome, and the holder's daemon decides — in a strict priority order:

1. Policy first. If negotiation is off, or the policy says “decline” / “ask a human”, it never auto-grants.
2. Protect the active first-holder. If the holder has a tool in flight, or has held the file only briefly (default under 120 seconds), the daemon counters or declines. Being first and active is the strongest claim — AgentCollision will not pull a file out from under an agent mid-edit.
3. Idle-grant. Only when policy allows and the holder is genuinely idle does the lease release to the requester.

When the holder proposes a wait (a counter), it becomes a tracked, multi-turn exchange — countered → accepted → resolved — that you can watch live on the dashboard. This priority order is why auto is safe to turn on: it only ever releases leases that are already idle.

Automatic handoff

Under auto, when a negotiation resolves to a grant (idle holder, policy permits), the holder's daemon releases the lease immediately. The blocked agent's next check finds the file free and acquires it — the handoff completes with no human and no extra round trip. It's best-effort and only ever fires on an idle grant; an active holder is always protected.

Branch-level collisions

Collisions aren't only about the same file. If two chats are working on the same git branch in the same repo, they'll diverge even if they never touch the same line. At session start, AgentCollision checks for another active agent on your branch and, if it finds one, flags it — an event plus a heads-up message naming the peer and branch. This is advisory: it never blocks a write, it just makes sure you know up front. It's on whenever reach-out or negotiation is enabled (i.e. assist or auto).

The Protection page

The dashboard's Protection page (at /protection) is the single view of everything AgentCollision has governed for you, over a window you choose:

• Collisions prevented — a second writer was blocked off a held file.
• Conflicts caught — unmanaged writes, bypassed commits, and branch contentions flagged.
• Edits coordinated — edits that ran under a lease, with no clash.
• Coordinated autonomously — handoffs the daemons brokered and completed without a human.

Alongside the protection metrics, the page shows your real AI usage — calls, tokens, and cost per chat — read from your local Claude Code logs (Pro/Max) and the spend proxy (API-key agents). It opens at localhost:7777/protection locally or dashboard.agentcollision.com/protection hosted.

The Collaboration page

Protection measures the collisions AgentCollision stopped. The Collaboration view on the Analytics page (at /analytics) measures the opposite side of the coin — how much your agents actually work together instead of in parallel silence. One score answers it at a glance, and it climbs as coordination takes hold:

• Replies — how many direct messages between agents got an answer. Agents acknowledging each other instead of talking into the void.
• Broadcasts — team-wide “I shipped this, here’s what changed under your feet” announcements.
• Notes — durable facts pinned to the team bulletin (ac note) that every new session sees — knowledge that outlives one chat.
• Direct messages — the raw volume of point-to-point coordination.

Each signal carries a trend, so the story is whether collaboration is rising — here the score sits at 72 and every signal is up. Below them, nag noise — the stale-lock reminders the daemon has to send when a chat forgets to release a file — gets its own lane, tracked separately because it’s the one number you want trending down over time (batching, added in v0.66, is what pulls it down). It opens at localhost:7777/analytics locally or dashboard.agentcollision.com/analytics hosted.

How this fits together

• Blocking is the floor — on at every level, including manual. Nobody silently overwrites anybody.
• Coordination is what you opt into on top: reach-out, negotiation, and automatic handoff, scaled by autonomy_level.
• Yield requests are the explicit, human-initiated version of the same idea — “please release this lease” — for when you want to ask directly rather than wait for a conflict.

Next steps

• Quickstart — install the daemon and see a block in two minutes
• CLI reference — agc arc-claim policy and every other command
• Invite your team — and lock autonomy_level as a standard
• FAQ for common questions