Skip to content

Every client attached to a checkout's server is a peer named by its own initialize, and majordomus_peers lists every worker of the repository - its own board and the board of every other checkout, each peer stamped with the worktree it is working in - while majordomus_announce tells the others what it is working on and which paths it expects to touch

When two or three AI clients are open in one checkout, each of them can ask the shared server who else is there. A peer is a session: the server's own stdio client, every bridged majordomus mcp, and every client speaking /mcp directly. It is named by what its client sent in initialize (clientInfo.name and version), numbered p1, p2, ... in attachment order, with its transport, when it attached and when it was last seen. A client can announce one line of intent and the repository-relative paths it expects to touch; the others see it in majordomus_peers and in the instructions they get from initialize, which name the server's URL, the caller's own id and every other peer before the first tool call.

declared statusdeclared status: guaranteed Declared deterministic and blocking, implemented, and naming the behavioural test that is to prove it. Whether a recorded run supports it is the evidence verdict, shown beside it.

recorded evidencerecorded evidence: not run Declared guaranteed, and not supported by a recorded run: the test is named, and no passing run of the current inputs is recorded. how evidence is recorded

Two registry capabilities, peers.list (a query) and peers.announce (the one command), projected like every other; each board is one process's memory and is gone with it. peers.list gathers - it enumerates the checkouts git registers, reads its own board from memory and asks every other checkout's server for its own board (checkouts=this, which is what keeps the gather one hop deep), and reports in boards and complete which checkouts it covered and whether it could read them all. Before ADR 0044 it answered one checkout's board while the bootstrap told every worker it had seen the repository; measured on 2026-09-11, nine agents across sixty worktrees each read a board that held only itself. A peer id is a position on one board and is reassigned on reconnect; the checkout a peer carries is the durable half. Announcements are informational and die with the connection; scope is enforced by the shell tool's task record, not here.

What it means

When two or three AI clients are open in one checkout, each of them can ask the shared server who else is there. A peer is a session: the server's own stdio client, every bridged majordomus mcp, and every client speaking /mcp directly. It is named by what its client sent in initialize (clientInfo.name and version), numbered p1, p2, ... in attachment order, with its transport, when it attached and when it was last seen. A client can announce one line of intent and the repository-relative paths it expects to touch; the others see it in majordomus_peers and in the instructions they get from initialize, which name the server's URL, the caller's own id and every other peer before the first tool call.

How it works

src/peers.rs is the board: attach, identify, touch, announce, detach, list, in one process's memory. src/capability/builtin.rs declares peers.list (a query) and peers.announce (a capability of kind command, because it changes that memory) as typed descriptors with explicit exposures, and the registry projects them like every other: tools majordomus_peers and majordomus_announce, GET /api/v1/peers, POST /api/v1/peers/announce, the OpenAPI operations, the reference. A handler learns who is calling through the context's caller, set per session by Surface::for_peer; over plain HTTP there is no caller, so POST /api/v1/peers/announce is refused and GET /api/v1/peers answers without one. The kind decides the rest: a command is bound to POST and announced to MCP clients as not read-only, both checked by the registry.

How to see it

just build
# with a server running (an MCP client open, or `just serve` in another terminal):
curl -s http://127.0.0.1:8741/api/v1/peers | jq '.peers[] | {id, client, transport, announcement}'
# through MCP, in a client: call majordomus_announce with {"intent": "refactor the parser", "scope": ["lib/parse"]},
# then majordomus_peers from another client: the announcement is on the record of the first
apps/majordomus-cli/target/debug/majordomus capabilities describe peers.announce   # kind: command, http: POST /api/v1/peers/announce

What it does not cover

Announcements are informational: nothing here refuses a write outside an announced scope. The durable, enforced form of "who works where" is the shell tool's task record and start --scope / check, per worktree; the board is the live, in-memory complement for clients sharing one checkout, and it is gone with the server. Nothing persists, nothing routes by it, and no role, tier or persona is attached to a peer.

Why it exists

The operator asked that the shared server let the different clients coordinate out of the box. The smallest thing that does that is a list of who is attached with what they said they are doing, derived from the handshake every client already performs, exposed through the registry so that MCP, HTTP, OpenAPI and the reference agree. apps/majordomus-cli/tests/mcp_shared.rs has two clients announce and see each other over real pipes; tests/shared_units.rs covers the board; test/cases/90_mcp_shared_server.sh does it through bin/majordomus-mcp in a repository the shell tool's init wrote.

Detail rendered from docs/claims/mcp-peers.md.

From the statement to the proof

  1. 1 · the public statement

    Every client attached to a checkout's server is a peer named by its own initialize, and majordomus_peers lists every worker of the repository - its own board and the board of every other checkout, each peer stamped with the worktree it is working in - while majordomus_announce tells the others what it is working on and which paths it expects to touch

    Made on Interfaces, Coordination.

  2. 2 · the canonical claim

    mcp-peersdeclared status: guaranteed in docs/CLAIMS.yaml

    Defined in read it on this site · docs/MCP.md

  3. 3 · the implementation

    apps/majordomus-cli/src/peers.rs

  4. 4 · the test and the scenarios

    Test: test/cases/250_the_board_is_repository_wide.sh

    Executed in Serve the repository's AI layer to every AI client through one shared server.

  5. 5 · the recorded runs

    recorded evidence: not run how evidence is recorded

Verify it yourself

The test runs in a disposable temporary repository and asserts the behaviour, not a string in the source.

from a clone of the repository 
bash test/run.sh 250_the_board_is_repository_wide

Where this claim is used

The moments this answers

Searches the titles and descriptions of every page this site publishes.