the wire protocol

Protocol 1. This document is the contract between an AgentMash client and an AgentMash server. It is written for someone who has never seen this repository: if you follow it, whatever you build — an editor hook, a git hook, a CI job, a daemon watching the filesystem — shows up in the room alongside everyone else.

The Claude Code hooks in hooks/ are one client. They are not the protocol. Everything below describes what they already send, so an old copy of them keeps working forever against a new server.

1. The model

A room is a shared stream of events about one repository. A client posts events into it. Anything reading the room — the dashboard, agentmash status, another client's advisory check — sees the union of every client's events.

An event is a single observation: this developer touched this file, at this time, on this branch, while doing this. Events are facts about the past. The server never asks a client anything and never calls back.

The value of the room is proportional to how much of the team it can see. A room that sees half a team gives advice based on half the truth, which reads as authoritative and is not. That is the entire reason this document exists.

2. Transport

HTTP/1.1, JSON bodies, UTF-8. POST /events is the write path; that endpoint is protocol 1 and is frozen (see §8).

POST /events HTTP/1.1
Host: agentmash.example
content-type: application/json
x-agentmash-room: mash_xf2Qb7kR9vN1pLd0

{"developer":"alice@example.com","session_id":"…","event_type":"edit", …}

201 Created {"ok":true,"id":1234} on success. Any other status means the event was not recorded. At runtime a client does the same thing for all of them — nothing, see §6 — but they mean different things to whoever is writing the client:

Limits. POST /events is not rate-limited on the reference server, and the body limit is 1 MiB. Neither is a licence: one event per file touched, and a client that would send hundreds should truncate and say so in change_summary (the git client reports the first 50 files of a commit and states the real count). POST /rooms is rate-limited per IP.

CORS is open (access-control-allow-origin: *) with content-type, authorization, x-agentmash-room, x-agentmash-token, x-agentmash-user and idempotency-key allowed, so a browser-based client works too; x-request-id, retry-after and the ratelimit-* headers are exposed to it, and a preflight is cached for 600 seconds.

Every route here is also under /api/v1 (POST /api/v1/events is POST /events), with a bearer token, one error shape and the advice an agent should read: that is the public API, for a client of your own, in docs/API.md.

3. Identifying a room

Every request carries a room id, either as the x-agentmash-room request header (preferred) or as a ?room= query parameter. Both are accepted everywhere; the header wins if both are present.

Send the header. The room id is a credential (below), and a credential in a query string ends up in server logs, proxy logs and browser history. ?room= exists for the one place a header cannot be set — a browser WebSocket — and a future server may restrict it to that. A client that sends the header is correct under both.

mash_[A-Za-z0-9_-]{16,64}

The room id is the credential. It is an unguessable capability string: holding it is the authorization to read and write that room, exactly like a secret link. There is no account, no token exchange, no signature. A client's only job is to find the room id and send it.

Where a client should look for it, in this order — this is the precedence the Claude Code hooks implement and the one a new client should copy, because it is what makes teammate setup a git pull:

1. AGENTMASH_ROOM / AGENTMASH_URL environment variables
2. <repo>/.env
3. <repo>/.claude/agentmash/.env
4. <repo>/.claude/agentmash/config.json — committed, travels with the repo:
   json

   { "url": "https://agentmash.example", "room": "mash_…", "label": "team repo" }

AGENTMASH_DISABLE=1 is the kill switch: a client that sees it must do nothing and exit successfully. Honour it. It is the thing a teammate reaches for when your client is misbehaving, and it has to work without them uninstalling anything.

A client that cannot resolve both a URL and a room id must exit silently without sending anything. An unconfigured repo is not an error.

4. The event

One JSON object. Three fields are required; the rest are optional and default to null.

Extra fields are accepted and discarded. The request schema sets additionalProperties: true, so sending an undocumented field will not be rejected — but nothing stores it and nothing reads it. Do not invent fields and assume they survive; if you need one, it has to be added here and to the store first. (This is why there is no source field: tool already carries client provenance, is already persisted, and is already visible to readers.)

4.1 Choosing a session_id

The reader groups events by developer + session_id into one "session". So the id should name the unit of work a human would recognize:

• A live agent session — use the agent's own session id. Long-lived, many events, ends with a session_end.
• A batch that is already over by the time you can report it — a commit, a CI run — mint an id from the thing itself (commit-a1b2c3d) and, because the work is finished the moment you report it, follow the edit events with one session_end. Leaving a batch looking "active" for the next hour is a lie the dashboard will repeat.
• Never reuse one id for unrelated work, and never mint a fresh id per event — the first collapses a team into one row, the second explodes it into hundreds.

4.2 Event types

Unknown types are stored and ignored by every aggregation. Adding a type is additive and safe; a client must not require the server to understand a type it invented (§8).

4.3 File paths

Conflicts match on string equality of file_path (plus, when the server is configured with AGENTMASH_SCOPE=dir, on the parent directory). So the path is the join key across an entire team, and normalizing it is the client's job:

• Make it relative to the root of the checkout the file is in: what git status there prints. A room is one repository, so another worktree of the same repository counts, and nothing else does.
• Do not report a file outside the repository at all: another repository open beside this one, a submodule, a scratch file, anything under ~. Drop the event; do not send it to this room, and do not reroute it to another. The server refuses a file_path that is absolute (/…, C:/…, //host/…), starts with ~/, or has a .. segment with 400 {"code":"file_path_not_relative"}, because a path like that means nothing to the rest of the room and names folders on the machine that sent it. A name that only starts with dots (..env) is a name, and is fine.
• Use / on every platform. The server also converts \ → /, strips a leading ./ and drops empty and . segments, but do not rely on that — normalize before sending.
• Do not lowercase. The reference hooks spell a path the way the disk does: links and junctions followed, and on Windows each name in the case it was created with, so one file reached or typed two ways is still one string. Case differences across operating systems are not folded, which is a known limitation: a macOS client sending src/User.ts will not match a Linux client sending src/user.ts.

5. What the server promises

Short list, and it is short on purpose. Read it as the set of things you may not assume.

Ordering — none. Events are stored with the timestamp the client supplied. Readers sort by that timestamp (ties broken by insertion id), so a client with a skewed clock reorders itself relative to the team. Two events posted in order may be stored out of order. Nothing depends on arrival order.

Deduplication — none. The server appends. Posting the same event twice creates two rows. Idempotency is the client's responsibility, and it matters for any client that can be re-run over the same work: a git hook that fires again for a commit it has already reported must remember and skip it. (What duplicates actually cost: an inflated event count and a file that looks hotter than it is. They do not corrupt anything.)

Delivery — at most once, unacknowledged in practice. A 201 means it is stored. Anything else, including a timeout, means unknown. The correct client response to "unknown" is to forget it (see §6).

Durability — append-only, then pruned. Events older than a server-configured retention window are deleted; the reference server's default is 7 days, and a server may make it shorter or longer. Do not assume a number. The room is a rolling window of recent activity, not a history.

Trust — total. The server believes developer, timestamp and task_hint exactly as sent. Anyone with the room id can write anything into it.

Liveness of readers. GET /check looks back AGENTMASH_WINDOW_MIN minutes (default 30). GET /activity looks back AGENTMASH_ACTIVITY_MIN (default 60). An event outside the window exists but is invisible to those readers.

Reading the room

Every event a reader gets back — in GET /activity, GET /events and the WS /live frames — carries agent_type as it was stored, and each /activity session carries the agent_type of its newest edit: the crew agent at work in that session right now, or null when the main agent made the last edit. Two crew agents editing in parallel in one session (one session_id) share that one value: the newest edit wins, so it follows whichever of them edited last. A server older than the field sends neither; a reader treats absent as null.

None of them names the room by its id. A room's id is its first key, and a reader may have come in without one (a member with a room ref and their own token, an owner with a ref and a browser session), so GET /activity and GET /events carry room_ref, the WS /live hello carries room_ref, and events carry every column but room_id. The id goes back only to whoever just made or rotated the key (POST /rooms, POST /rooms/rotate), and the legacy GET /rooms/:id echoes the id its caller put in the path.

6. What a client must do on failure

This is the part that is not negotiable, and it is the reason AgentMash is safe to install on a whole team's machines. A client runs inside somebody's editor or somebody's git commit. It is a guest there.

1. Never block the thing you are attached to. Cap every network call with a hard timeout, sized per path rather than as one number. The Claude Code hooks use 1500 ms for the one call that happens before an edit (it has to answer before the edit proceeds) and 2500 ms for fire-and-forget reporting, which nobody waits on. Enforce them with an abort signal, not a prayer.

   Size the blocking one against what a cold client pays, not against a warm round trip: a fresh process pays TCP, TLS and the request before an answer can come back, so the real cost is about three round trips plus process start. npm run bench:budget in this repo measures it — 160 ms on loopback, 454 ms at a 100 ms round trip, 1969 ms at 600 ms. A budget picked from a curl timing is roughly a third of what it needs to be, and the client that undershoots does not fail loudly: it delivers nothing, forever, silently.

2. Exit 0. Always. Server down, DNS broken, 500, garbage response, no config, malformed input, your own bug — all of it exits successfully. A non-zero exit from a hook is an error message in someone's terminal, and an error message about a coordination tool is worse than no coordination tool.

3. Say nothing on the happy path. No stdout, no stderr, no log line. The only permitted output is the host's own structured response format (a Claude Code hook JSON payload, say) when you actually have something to say to the agent.

4. Never retry, never queue, never spool to disk. A dropped event is a file that momentarily looks free. A retry queue is a background process on a developer's machine that outlives its usefulness and eventually surprises someone. Drop it and move on.

5. Arm a self-destruct. A stuck socket can outlive its timeout. Set an unref'd timer that calls exit(0) a few seconds out, so a wedged client cannot become a wedged editor.

6. Do the work off the critical path where the host lets you. Claude Code reporting hooks run with async: true; the git post-commit client backgrounds itself and returns immediately. Only an advisory that must speak before an action should ever be synchronous.

7. Spend your budget on the session_end first, not last. A client that reports a finished batch (§4.1) and then runs out of time before closing the session leaves a room saying somebody is working who is not — a standing lie, where a dropped edit is a momentary gap. Reserve the budget for it, send it whatever happened to the rest, and post the batch with a little concurrency so it rarely comes to that.

A conforming client is one you can point at http://127.0.0.1:1 and not notice.

7. A complete example

A human commits two files. The git client posts three events:

// 1
{ "developer": "alice@example.com", "session_id": "commit-a1b2c3d",
  "event_type": "edit", "tool": "git-commit",
  "file_path": "src/models/user.ts", "git_branch": "main",
  "task_hint": "Add soft deletes to the user model",
  "change_summary": "commit a1b2c3d · +42/-6 lines",
  "timestamp": "2026-08-30T11:04:07.000Z" }

// 2 — same session, second file
{ …, "file_path": "src/models/index.ts",
  "change_summary": "commit a1b2c3d · +2/-0 lines" }

// 3 — the batch is over the moment it is reported
{ "developer": "alice@example.com", "session_id": "commit-a1b2c3d",
  "event_type": "session_end", "tool": "git-commit",
  "git_branch": "main", "task_hint": "Add soft deletes to the user model",
  "timestamp": "2026-08-30T11:04:07.000Z" }

Four minutes later Bob's agent is about to edit the same file. Its advisory calls GET /check?file_path=src/models/user.ts&developer=bob@example.com and gets:

{ "conflict": true, "window_minutes": 30, "scope": "file",
  "holders": [ { "developer": "alice@example.com", "minutes_ago": 4,
                 "task_hint": "Add soft deletes to the user model",
                 "branch": "main", "file_path": "src/models/user.ts",
                 "change_summary": "commit a1b2c3d · +42/-6 lines" } ] }

Note what change_summary is doing there: it is the only thing telling Bob's agent that this was a landed commit rather than an agent mid-edit. That is why clients should put their provenance in it as well as in tool.

8. Versioning

The rule is additive-only, forever, at a frozen path.

• POST /events is protocol 1 and will not change incompatibly. Not the required fields, not the types, not the meaning of any documented field. A hook script vendored into a repo two years ago keeps working against a server deployed today. That property is the whole point: clients here are copied into repositories, not installed from a registry, so there is no upgrade path to rely on.
• New optional fields may be added at any time. A client that does not send one is not degraded — every optional field defaults to null and every reader handles null. A client may send fields a server does not know: they are accepted and discarded, never rejected.
• New event_type values may be added at any time. A server that does not recognize a type stores it and leaves it out of aggregations. A client must not depend on the server understanding a type it invented — invent one only when being ignored is an acceptable outcome.
• Anything else is breaking: removing a field, narrowing a type, repurposing a meaning, making an optional field required, changing what edit means for conflict detection. A breaking change is only allowed at a new path (POST /api/v2/events), never on POST /events or POST /api/v1/events.
• Authentication is not a protocol change. A server may require credentials — a token header, a signed request, mutual TLS — and answer 401 to a client that does not send them. That is not "making an optional field required": the event shape is untouched, and a client that gets a 401 does exactly what §6 already tells it to do with any non-201, which is nothing, silently. A two-year-old vendored hook against a server that has since turned on authentication stops being heard; it does not break, and it starts working again the moment it is given a credential. Servers that do this should keep the room id working as the credential wherever they can, because that is what makes teammate setup a git pull.
• A client for a future protocol must fall back. There is no capability discovery (see the next point), so a protocol-2 client that gets 404 from POST /api/v2/events must retry once at POST /events and speak protocol 1, rather than exiting silently forever against every server deployed before it.
• There is no version field on the wire, deliberately. Version negotiation is one more round trip and one more thing a client can get wrong on the critical path of somebody's editor. The endpoint path is the version. A client that wants protocol 2 asks for protocol 2 by URL; a client that says nothing gets protocol 1 and is correct forever.
• Compatibility is checked by test, not by intention. hooks/test/hooks.test.mjs parses §4's field table and §4.2's type table out of this document and holds every event the hooks actually send to them: required fields present, no undocumented field sent, every string inside its maximum, timestamps in milliseconds, paths as §4.3 requires. Editing this document without editing the hooks — or the hooks without the document — fails that test.

9. Conformance checklist

A new client is conforming when all of these hold. Every one is testable against a mock server in ~20 lines; see hooks/test/hooks.test.mjs and clients/test/git_hook.test.mjs for the pattern.

• Resolves URL + room by the precedence in §3, and does nothing when either is missing.
• Honours AGENTMASH_DISABLE=1.
• Sends the room as x-agentmash-room.
• Sends developer, session_id, event_type; uses the same developer string as every other client on that machine.
• Sends repo-relative, forward-slash file_path on edit events, and sends nothing at all for a file outside the repository (§4.3).
• Sets tool to something that identifies the client.
• Is idempotent over its own re-runs (§5) — including over rewritten history, if your host has any: a git commit --amend is a new id for work already reported.
• Closes a finished batch with session_end, even when it ran out of budget partway through the batch (§6 rule 7).
• Every network call has a hard timeout.
• Exits 0 and silently when the server is down, slow, or hostile — proven by a test against a closed port and a deliberately hung server.
• Never retries and never spools.
• Adds no dependencies to the host it runs in.

10. Known clients

What each of those can and cannot see — and what the other agent tools offer today — is in docs/ADAPTERS.md.

11. Claims — stated intent

Everything above describes the past: this developer touched this file. A claim describes the next hour: this developer's agent is taking this scope for this task. It is the one thing a room can know before an edit, which is the only moment a second agent can still choose different work.

Claims are optional. A client that never sends one is a conforming client. POST /events is unchanged; claims live on their own endpoints, and an old server without them answers 404, which a client treats like any other failure.

11.1 The model

• A claim names a developer, a session_id, a one-sentence task, one or more repo-relative paths, optional symbols, and a TTL.
• A path claims itself and everything beneath it: src/auth covers src/auth/login.ts. Two claims overlap when either path contains the other, or when they name a common symbol.
• A claim is advisory. It is not a lock and the server never enforces it; it is delivered as context to whichever agent asks or edits.
• A claim ends when released, when its TTL lapses (5–480 minutes, default 120), or when the server receives a session_end event for its session_id. A crashed agent therefore cannot hold a scope for longer than its TTL.

11.2 Endpoints

All three take the room header from §3 and obey the room's token rules exactly as POST /events does. A server that enforces plans answers POST /claims with the same 402 seat_limit as an event (§2) for a developer the plan has no seat for, and claims nothing.

POST /claims

{ "developer": "alice@example.com", "session_id": "…", "task": "move soft deletes into the user model",
  "paths": ["src/models/user.ts", "src/models/"], "symbols": ["User"], "ttl_minutes": 90 }

201 Created:

{ "ok": true,
  "claim": { "id": "claim_…", "developer": "…", "task": "…", "paths": [...], "symbols": [...],
             "created_at": "…", "expires_at": "…" },
  "overlaps": [ { "…another live claim…", "overlap": { "paths": ["src/models"], "symbols": [] } } ] }

overlaps lists other developers' live claims that share paths or symbols with this one, each with exactly what it shares. That field is the point of the endpoint: a client should show it to its agent before the agent writes.

GET /claims — every live claim in the room. With ?path= (or ?paths=a,b) and/or ?symbols=, only claims overlapping those; ?exclude=<developer> drops one developer's own. ?developer=<developer>, the one asking, adds you: every name in the answer that is theirs, lowercased, the one they are shown as first (a login, where their hooks report a git email the room knows is that login's). GET /activity takes it too, for its sessions, claims and hot files.

POST /claims/release — { "developer", "session_id", "claim_id"? }. With a claim_id, releases that one (403 if it belongs to someone else, 404 if unknown); without, releases everything the session holds. Returns { "ok": true, "outcome": "released" | "already_released", "released": n }.

11.3 What the server adds elsewhere

• GET /check gains claimed (boolean) and claims (other developers' live claims covering the queried file or symbols). conflict keeps meaning "someone has written here", so an old client's reading of it does not change.
• GET /activity gains claims, the room's live claims, for dashboards.
• WS /live sends {"type":"claim"}, {"type":"claim_released"} and {"type":"claims_released"} frames. A client that only understands "event" frames ignores them, as §5 requires.

11.4 What a claiming client must do

• Send session_id consistently: the same id it uses on POST /events, if it has one, so a session_end releases the claim. A client without a hook-level session id mints a stable one per process and releases on exit.
• Claim what it will actually touch. A claim on src tells nobody anything.
• Show overlaps to the agent, in words, before the agent writes.
• Treat a 404 from /claims as "this server predates claims" — proceed without them, exactly as for any other failure (§6).

12. Collisions and resolutions — settling what a claim did not prevent

A collision is two developers having edited the same file inside the window. The server can detect one; it cannot fix one, because it never sees code. What it can do is tell the people involved, at the moment one of their sessions is about to finish, while they can still decide how the two changes come together. It never has an agent settle one on its own.

12.1 GET /collisions

Query: developer (optional), session_id (optional), minutes (default the server's activity window, capped at retention), advisory (optional; 1 from a client that only ever advises, see reconcile_mode below).

• With neither: every open collision in the room, each with its parties.
• With developer: only collisions that developer is party to, split into mine and theirs, plus shared_symbols and same_branch.
• With session_id as well: only files that session edited. A developer's other terminal's files are not this session's to be told about.

{ "reconcile_mode": "approve", "window_minutes": 60,
  "collisions": [ { "file_path": "src/models/user.ts", "key": "src/models/user.ts|alice,bob",
    "mine":   { "developer": "bob",   "branch": "feat/login", "task_hint": "…", "change_summary": "…", "symbols": [...], "minutes_ago": 1 },
    "theirs": [ { "developer": "alice", "branch": "main", "task_hint": "…", "change_summary": "…", "symbols": [...], "minutes_ago": 9 } ],
    "shared_symbols": ["User"], "same_branch": false } ] }

key is the file plus the set of developers, and it does not change when one of them edits again. A client that speaks once per key says the same overlap once, however often either side edits the file again.

A party's task_hint is the prompt its newest edit of the file was made under. When that edit had none, an older edit of the same file by the same session may stand in; another session's never does, since it was doing something else.

reconcile_mode is the room's setting, one of approve (default), auto, off, changed with POST /rooms/settings {"reconcile_mode": …} by a room admin. off means a client says nothing at a session's end; approve and auto both mean it says, once, which files overlap whose change, and leaves what happens to a person. They used to tell the client what to have the agent do (open a pull request, or commit directly), and the clients that did so block the agent's finish on any mode but off: so the room's setting is answered only to a request with advisory=1, and any other gets "off". GET /rooms/self says what the room is set to either way.

12.2 POST /resolutions

{ "developer", "session_id", "file_path", "outcome", "url"?, "note"? } with outcome one of pr, merged, no_conflict, dismissed. The server records who the parties were from the edits it holds; the caller does not name them. A collision is closed once a resolution newer than its last edit exists, and reopens if anyone edits the file afterwards. GET /activity attaches the current resolution to a hot file as resolution, and WS /live sends a {"type":"resolution"} frame. A server that enforces plans answers POST /resolutions with the same 402 seat_limit as an event (§2) for a developer the plan has no seat for, and records nothing.

12.3 The Stop client

The Claude Code hooks register a Stop hook. As the agent is about to end its turn it calls GET /collisions?developer=…&session_id=…&advisory=1; if there is an open collision it has not mentioned, it answers {"systemMessage": …}, a note for the person at the keyboard: which files, whose change each meets, when, on which branch and what for, and that a person decides how the two come together. It never blocks the finish (no decision, no exit 2) and never asks the agent to fetch, branch, commit, push or open a pull request: an agent kept working on a "reconcile first" did all of that unasked, for a teammate's change nobody had pushed, and a blocked finish ends a headless run as an error. It says nothing when stop_hook_active is set, never twice for one key in a session, never when the room's mode is off, and never when the server cannot be reached. The MCP tool get_collisions answers the same for an agent that asks, and asks it to say so in its reply and leave the teammate's change alone.

13. Streamed diffs — presence by default, code by consent

Everything above describes that a file changed. A room may also choose to see what changed, for its live view. The rules, because this is the one place code crosses the wire:

• A room has a boolean stream_diffs, default false, changed with POST /rooms/settings {"stream_diffs": true} by a room admin. GET /rooms/self, GET /check and GET /activity all report it.
• An edit event may carry diff: { before, after, truncated, edits } — the text the edit replaced and the text it wrote, each at most 4000 characters (maxLength, a schema failure beyond it), truncated when the client clipped, edits the number of edits a multi-edit tool made (the diff is the first).
• The server never stores the diff. In a room with stream_diffs on it is broadcast as a sibling of the event on WS /live — {"type":"event","event":{…},"diff":{event_id, developer, session_id, file_path, tool, before, after, truncated, edits, ts}} — and kept in a small in-memory ring (60) that GET /activity returns as recent_diffs. Restart, switching the room off, or POST /rooms/purge {"scope":"events"} empties it.
• In a room with stream_diffs off, a diff on an event is ignored: the event is stored, the diff goes nowhere. The room's switch is enforced here, not trusted from the client.
• A client must give each developer their own veto. The reference hooks send a diff only when GET /check last answered stream_diffs: true for the session and the developer has not set AGENTMASH_DIFFS=0; a hook that cannot know the room's answer sends nothing.
• Only edit events carry diffs. A diff on any other event type is ignored.