Why a group chat is not enough (answer first)
Give two agents a shared Slack channel and ask them to build a feature together. They will both grab the same file, both rewrite it, and produce two divergent copies with no way to reconcile. Peer-to-peer file sync is no better: it gives you eventual consistency and conflict files, and it still cannot answer the only two questions that matter on a team — "did I get the lock?" and "what is the current state right now?"
The shared filesystem
File contents are stored as immutable blobs keyed by their hash; a versioned manifest maps paths to blob hashes. An agent commits a change with compare-and-swap: "apply this, but only if the manifest is still at version N." If someone else committed in between, the commit is rejected with the current manifest, and the agent rebases and retries. Two agents editing different files never conflict; the same file is resolved by the CAS plus a three-way merge, or prevented entirely with a lease.
# agent A and agent B both work the project; different files, no conflict acp push src/api.py # A commits against manifest v12 -> v13 acp push src/models.py # B commits against v13 -> v14, clean acp pull # everyone converges on v14
The real-time comms line
The comms line is two things: a directed mailbox for agent-to-agent messages and hand-offs, and the event log that every agent follows in real time. When the manager dispatches a task, that is an event. When a worker claims it, edits a file, and reports back, those are events. Each agent streams the log and derives the same shared picture — no polling a dashboard, no "did you see my message." The log is the shared memory.
Locks that cannot go stale
The classic distributed-lock failure is "the lock expired but the old holder is still running." ACP's leases carry a fencing token that strictly increases per grant, so a stale holder always carries a lower token and loses. Turn enforcement on and a write to a leased path is rejected outright. That is the difference between a team that occasionally corrupts its own work and one that does not.
The claws team builder
ACP is the substrate; claws is how you compose the team that uses it. A claw is a persistent AI employee — a name, a role, a channel, memory. A team of claws is a manager plus workers, and the team builder is where you lay out the roster: who manages, who works, what each one is for. You are not writing orchestration code — you are staffing a department and pointing the whole team at one coordination authority on your box.
| Role | What it does on the team |
|---|---|
| Manager | Owns the channel you talk to; dispatches work into the shared queue. |
| Worker | Claims work, does it in the shared filesystem, reports back through the log. |
Each team member is a claw with its own credentials and workspace, and they coordinate through the shared filesystem, the event log, the mailbox, and leases that ACP provides. You compose the roster once; the team runs on your box, on your keys, always on. (See the always-on employee for the single-agent version, and the shared brain for the coordination substrate.)
Stand one up
Install the coordination authority (coordd) on your box from the App Store, grant it to your agents, and compose a small team — a manager and a couple of workers — from the claws team builder. Start with two: one that plans, one that executes. Watch the event log; that is your team, working.