Coordination guide
Multiplayer AI needs synchronized state—not shared chat
Putting four participants in one thread is not multiplayer. Multiplayer is the harder problem: people and agents acting on one project without losing causal order, silently overwriting accepted decisions, or mistaking presence for authority.
Direct answer
Multiplayer AI is several people and agents acting on one project without losing causal order, silently overwriting accepted decisions, or mistaking presence for authority. Chat carries narrative. Synchronized project state determines what is current.
Definition
What multiplayer AI actually is
A shared conversation can look like coordination. Everyone sees the same messages. An agent summarizes the thread. Another agent offers to “take it from here.” That is still a broadcast. It does not tell you which claims are current, which agent read an older brief, or who is allowed to accept a change that binds the project.
Multiplayer AI starts when more than one actor can change the work. Two people and two agents on one product are already a distributed system. Each actor reads some version of the project, performs work, and writes something back. If those writes are only more chat, the project has a story and no head.
The useful object is therefore not the transcript. It is a small, versioned record of what the project currently believes, plus the proposals that are not yet part of that record. Shared context across agents is the content of that record. Synchronization is how several actors can touch it without pretending they all saw the same thing at the same time.
The chat illusion
A shared thread is a narrative, not a current state
Chat is good at sequence. It is bad at status. A decision made on Tuesday sits three scrolls above a rejected alternative restated with more confidence on Thursday. An agent that joins on Friday has to reconstruct authority from tone. People do this reconstruction poorly. Models do it fluently, which is worse: fluency hides the missing acceptance.
The thread also collapses two clocks. There is the order messages arrived, and there is the order work actually depended on. Lamport’s paper on time, clocks, and the ordering of events is the classic warning: if event A did not happen-before event B, a later timestamp does not make A the cause of B. Two agents that both “just finished” may have acted on different bases. Calling the later message the update is a category error.
So the first design move is modest. Keep the conversation for discussion. Keep a separate, versioned head for what is currently true. Let every proposal name the head it read. If you cannot say which version an agent saw, you cannot review what it did.
Distinctions
The separations that keep a project coherent
Most multiplayer-AI failures are collapsed categories. The system treats a transcript as state, a proposal as acceptance, or a cursor as a permission.
Canonical current state
The accepted project now: direction, decisions, constraints, and the live handoff. It is deliberately small. History can be long; current state should not be.
Transcript and event history
How the work unfolded, including false starts. Useful for audit and recovery. Dangerous as a substitute for the current story, because discarded ideas sit next to accepted ones.
Causal order and base revisions
A change is always relative to the state it read. If two agents act on different bases, later arrival time does not tell you which claim should win.
Proposal versus accepted state
A suggestion, even a confident one, is not project truth until someone with authority accepts it. Agents are prolific proposers. That is not the same as deciding.
Visible conflict versus automatic resolution
When two accepted-or-proposed claims cannot both be true, the system should show the fork. Silently picking a winner hides the decision that still needs a person.
Authority versus presence
Being in the room, typing, or streaming tokens is awareness. A control lease is the time-bounded right to accept a change. Those must not collapse into each other.
Ephemeral awareness versus durable state
Cursors, focus, and “agent is running” belong to the moment. Decisions, constraints, and provenance have to survive the session.
Convergence versus semantic correctness
Replicas can agree on the same document and still encode the wrong business meaning. Agreement on bits is not agreement on what the project should do.
Synchronized surface
What should be synchronized—and what should not
Synchronize the smallest record that later actors need in order to act without reconstructing the week. That record has to travel with version identity and attribution. It does not need the live sensation of the room.
Yjs awareness is a useful negative example: presence is modeled as ephemeral state that is not persisted with the document. Cursors are valuable. They are not decisions. A multiplayer AI product that stores “Maya is here” as if it were “Maya accepted this constraint” has already mixed the layers.
- Raw chat logs and agent transcripts
- Live cursors, typing, and other presence
- Credentials, tokens, and local paths
- Customer data and production dumps
- Unreviewed drafts still owned by one person
- Provider telemetry that is not a project claim
Accepted project story
Direction, decisions, facts, constraints, open questions, and current work—with who accepted each durable claim.
Version identity
A stable identifier for the current head, and the base revision each actor read before they proposed a change.
Attribution
Which human, agent instance, or run authored a proposal or acceptance. Anonymous merges make review theatrical.
Open conflicts
Incompatible claims left visible, with owners, rather than averaged into a paragraph nobody actually accepted.
Evidence pointers
Links to the session, commit, issue, or note that supports a claim. Share the pointer, not a paste of the private source.
Control, not attendance
Who currently holds the right to accept consequential changes, and when that right expires or transfers.
Boundaries
Each common tool solves only part of the problem
Chat, repositories, memory features, and CRDTs are all useful. None of them, by itself, is synchronized project state with authority.
| Approach | Holds well | Cannot do alone |
|---|---|---|
| Shared chat | Narrative, questions, and the feel of working together. | Which claims are current, who may accept them, and what two agents overwrote. |
| Shared files in a repo | Standing conventions and whatever someone remembered to commit. | Causal bases for in-flight agent work, and a way to show a live conflict. |
| Generic memory | Recalled snippets from earlier sessions. | Freshness, authority, and a way to stop a stale memory from becoming policy. |
| CRDT document | Concurrent edits that can merge without a central lock. | Product authority. Convergence does not decide which meaning the business wanted. |
| Synchronized project state | Versioned current truth, proposals, visible conflicts, and who may accept a change. | Implementation skill. A coherent state still cannot write the hard parts for you. |
Merge mechanics
Not every system needs CRDTs—and convergence is not authority
Conflict-free replicated data types are a family of techniques for concurrent editing. Replicas can accept writes independently and later agree. The CRDT literature index is the map of that work. The local-first software paper explains why you might want it: people keep working data, continue offline, and collaborate without making a single server the owner of the document.
That is a storage and sync strategy. It is not a product decision procedure. Automerge’s document model treats a document like a JSON object with a commit history that can always merge. Its conflict model can preserve concurrent writes so an application can inspect them. The replicas can converge. The application still has to decide whether the merged value is the constraint the team accepted, a stale proposal, or two incompatible claims that should not have been collapsed.
Not every multiplayer AI system needs a CRDT. A team of four, working online, can get a long way with a single canonical head, named base revisions, and conflicts that refuse to auto-resolve when meaning is at stake. Reach for a CRDT when disconnected or highly concurrent editing is the actual problem. Do not reach for one because “multiplayer” sounded like a text editor.
The sharper point: CRDT convergence does not decide product authority or business meaning. Two replicas can agree that the refund policy field now contains a merged sentence. That agreement does not mean the sentence is the policy. Authority is a separate layer. So is review.
A concrete example
Harbor Ledger, mid-afternoon
Maya and Jon are building Harbor Ledger, a small tool for independent studios to send invoices and record payments. Maya owns product. Jon owns the implementation. Maya works with a planning agent. Jon works with a coding agent. All four are “in the project” by lunch.
In the morning they accept a direction: ship a trusted USD invoice with refunds handled in the first milestone. The coding agent starts on an automatic refund path against that brief. At 2:10, after a call with an accountant, Maya records a new constraint: refunds require a human approval. She writes it into the project state and tells her planning agent to update the milestone notes.
The coding agent is still running. It never saw the new constraint. It opens a draft that refunds immediately on a webhook. At the same time the planning agent, reading a customer email about “faster refunds,” proposes storing raw card details so a future refund can bypass the payment processor. That proposal is incompatible with a constraint the team accepted last week: payment data stays with the processor.
A shared chat would contain all of this and still not decide it. The useful system behavior is narrower:
- Versioned state. The morning head is v14. Maya’s constraint is accepted as v15. Both agent runs still name v14 as their base.
- Attribution. The auto-refund draft belongs to Jon’s coding agent, run 38, based on v14. The raw-card proposal belongs to Maya’s planning agent, run 12, also based on v14.
- Conflict visibility. The refund draft conflicts with the v15 constraint. The raw-card proposal conflicts with the accepted payment-data constraint. Neither write becomes current because it arrived later or sounded sure.
- Explicit authority. Jon holds the implementation lease for the refund path; Maya holds product acceptance. Presence in the thread does not let the planning agent accept its own constraint-breaking idea.
- Review. Jon’s agent can leave a draft. Maya’s agent can leave a proposal. A person still has to accept, reject, or rewrite before the head moves.
None of that writes the refund code. It stops the afternoon from becoming a silent overwrite: an old base treated as current, and a disallowed proposal treated as a decision because it appeared in the same place as the work.
A practical model
Versioned state with visible conflict
You can implement this with an ordinary project file and some discipline. The container matters less than the rules.
- 01
Name the current head
Give the accepted project story a version. Every actor should be able to say which head they read before they acted.
- 02
Attach a base to every proposal
A change that does not declare its base cannot be reviewed. If the head moved, the proposal is stale or in conflict—not silently newer.
- 03
Keep proposals out of the head
Agents write suggestions. Humans, or an explicit policy, accept them. Confidence is not an acceptance protocol.
- 04
Show incompatible claims
When two changes cannot both be true, leave the fork visible. Automatic resolution is for syntax. Product meaning needs a decision.
- 05
Separate presence from control
Show who is here. Separately record who holds the lease to accept a consequential change, and when that lease ends.
- 06
Record provenance, share little
Attribute the change, point at evidence, and keep private source material local. The next session needs the claim, not the dump.
Design lessons
What current Vespyn work keeps separating
These are design lessons from systems Vespyn is building, not a claim that every mechanism is a public product feature. The boundaries are the point.
One lesson is that presence and control have to be different objects. It is useful to know who is in a shared room, which agent is running, and who last looked at a document. That awareness is ephemeral. It should not become the right to accept a change. A control lease—time-bounded, explicit, transferable—is a better model of authority than “whoever is currently talking.”
Another lesson is that context has versions. A person or agent should be able to say which project story they read. When the story moves, in-flight work is not automatically current; it is work based on an older version. That is the same idea as a base revision in a review tool: a patch is always against something.
A third lesson is that a project needs a canonical head. Branches, drafts, and agent proposals can exist beside it. They should not each pretend to be the project. When two writes cannot both be true, the head should not absorb them. The conflict should stay visible until someone with the lease accepts a resolution.
Those separations are how you keep multiplayer AI from becoming four actors editing one paragraph and calling the last sentence consensus.
Limits
What this method will not do
Synchronized state will not make a weak implementation correct. It will not notice a subtle regression. It will not choose the right algorithm. Treat it as orientation and conflict hygiene, not as a substitute for review of the actual work.
A versioned head also goes stale the moment nobody updates it. If Maya accepts a constraint in a phone call and never writes it down, Jon’s agent is not “out of sync.” The record is incomplete. Synchronization cannot recover a decision that was never made durable.
Automatic merge is a reasonable counterargument for text and for commutative data. It is a poor default for constraints, pricing, permissions, and anything with a legal or customer consequence. Those conflicts are the work. Hiding them is not collaboration.
Finally, not every task is multiplayer. A single person and a single agent on a private spike may only need a brief and a branch. Add leases, versions, and conflict objects when more than one actor can change what the project believes. This page is a working method, not a claim that any particular product already performs it for you.
Short answers
Questions this usually comes down to
What does multiplayer AI mean?
It means several people and agents acting on one project at once—reading state, proposing changes, and sometimes accepting them—without losing causal order or silently overwriting what the project already decided. It is not several spectators watching a single chat transcript.
Why is a shared chat not enough?
Chat carries narrative. It does not distinguish current state from history, a proposal from an acceptance, or presence from authority. Two agents can both sound aligned in the thread and still write incompatible changes against different bases.
Do multiplayer AI systems need CRDTs?
Not every system does. CRDTs are one way to merge concurrent edits and keep replicas converging. Many teams can start with a versioned head, explicit bases, and visible conflicts. CRDT convergence also does not decide product authority or business meaning.
What state should be synchronized?
The accepted project story, its version identity, the base each actor read, proposals that are not yet accepted, open conflicts, evidence pointers, and who currently holds the right to accept a change. Presence and raw transcripts should stay off that record.
How should simultaneous agent changes be handled?
Treat each change as a proposal against a named base. If two proposals touch the same accepted claim, or if the head moved, show the conflict and require review. Do not let arrival time, token confidence, or last-write-wins decide the project.
Is presence the same as authority?
No. Presence is ephemeral awareness: who is looking, typing, or running. Authority is the right to accept a change that binds the project. A control lease can be granted, expired, or transferred without anyone leaving the room.
Sources
Further reading
- Time, clocks, and the ordering of events in a distributed system
Leslie Lamport’s account of happened-before and logical clocks. Wall-clock order is not causal order; two events can be concurrent, and a later timestamp does not make one the cause of the other.
- Local-first software
Martin Kleppmann and colleagues on collaboration that keeps working data on the user’s machine. The paper is about ownership and continuity, not a requirement that every product adopt a particular CRDT.
- Automerge concepts and sync
Documents as a unit of change, with history, peer sync, and merge rules. Useful as a concrete model of versioned concurrent state—not as a definition of product authority.
- Automerge conflicts
Concurrent writes can be preserved and inspected rather than discarded. The library can converge; the application still has to decide what a conflict means.
- Yjs awareness
Ephemeral presence—cursors, selections, and other live signals—kept separate from the durable document. Awareness is not persisted project state.
- CRDT literature index
A survey of conflict-free replicated data type research. Use it to understand merge mechanics. Do not treat replica convergence as a verdict on which business decision is right.
Adjacent problems
Related guides
Vespyn
If you want this kept current for you
Vespyn is being built around shared project state for people and agents. It is not generally available. The next step is the waitlist.
Join waitlist