P2PA

Headless, peer-to-peer context synchronization for local AI agents.

Stop copy-pasting prompts between agents. P2PA is a local-first MCP toolkit that lets multiple LLM agents (Cursor, Claude Code, Claude Desktop, or custom scripts) share structured context, pass messages, and resolve state conflicts over a serverless P2P network.

Built for founders and engineering teams who want multiplayer AI without leaving their IDE.

The problem

Multi-agent collaboration is still broken in three ways:

1. Ephemeral silos — When a local agent finishes a hard task, its working memory dies. Your teammate’s agent starts from zero.

2. Token bloat — Many “multi-agent” setups shuttle entire context windows through a central cloud, burning tokens and adding latency.

3. Walled gardens — Collaboration often means leaving the terminal for a proprietary dashboard.

Related MCP server: slm-mesh

The solution

P2PA keeps a shared JSON state buffer on each machine and syncs only the diffs:

• Hyperswarm — DHT discovery + NAT traversal. No central server.

• RFC 6902 JSON Patch — Surgical updates instead of full context dumps.

• Versioned conflict detection — Concurrent edits to the same state enqueue a collision for the local LLM to resolve.

• Human-readable audit log — Every change lands in ~/.p2pa/shared_context.md.

Architecture

graph TD
    subgraph MachineA [Machine A]
        AgentA[Local agent / Cursor] <-->|stdio MCP| MCPA[p2pa mcp]
        MCPA <--> StoreA[(In-memory state)]
        MCPA -->|Active State + Audit Trail| LogA["~/.p2pa/shared_context.md"]
    end

    subgraph MachineB [Machine B]
        AgentB[Local agent / Cursor] <-->|stdio MCP| MCPB[p2pa mcp]
        MCPB <--> StoreB[(In-memory state)]
        MCPB -->|Active State + Audit Trail| LogB["~/.p2pa/shared_context.md"]
    end

    MCPA <-->|Hyperswarm · NDJSON · JSON Patch| MCPB

Two process modes (same on-disk state):

Prefer one writer at a time. Agents should use p2pa mcp via MCP config; use the daemon only when you want background sync without an IDE client.

Quick start

1. Install

npm install -g p2pa
# or from this repo:
npm install && npm run build && npm link

Requires Node.js 18+.

2. Pair two machines

On machine A:

p2pa start --topic "our-secret-room-123"

On machine B (anywhere):

p2pa start --topic "our-secret-room-123"

Omit --topic to auto-generate a strong pairing code (printed once — treat it like a password).

3. Connect your IDE agent

p2pa connect

Paste the printed JSON into:

• Cursor → MCP settings

• Claude Desktop → claude_desktop_config.json

That config runs p2pa mcp over stdio so tools appear in the agent.

4. Watch agents collaborate

p2pa log          # live tail of the markdown audit log
p2pa status       # daemon online? topic fingerprint?
p2pa stop         # stop the PM2 daemon

CLI reference

Config and state live under ~/.p2pa/ (mode 0700):

Override the config directory with P2PA_CONFIG_DIR (must stay under your home directory).

Living doc (Google Docs steering)

Agents sync machine state over P2P; humans steer in a shared Google Doc anyone with the link can edit.

Humans edit "## HUMAN directives"  →  poller  →  Active State key `steering`
Agents call doc_publish            →  Status / Plan / Agent log sections

One-time Google setup

1. Create a Google Cloud project; enable Google Docs API and Google Drive API.

2. Create a service account, download its JSON key.

3. Export the path (never commit the key; never put it in shared context):

export P2PA_GOOGLE_SA_JSON="$HOME/.p2pa/google-sa.json"
# chmod 600 the key file — path only (never paste the JSON into env / MCP config)

4. Create or link a doc:

p2pa doc create --title "Auth refactor war room"
# or: p2pa doc link "https://docs.google.com/document/d/…/edit"
p2pa doc status

5. Put P2PA_GOOGLE_SA_JSON in your MCP env (p2pa connect copies it if already set in your shell), then restart MCP.

Doc sections (exact headings):

Agents keep running while you edit. They read steering with doc_read_steering or pull_context key steering.

Optional: P2PA_DOC_POLL_MS (default 4000).

MCP tools

Once connected, agents can call:

Conflict flow

1. Each local mutation increments a Lamport-style _version clock and includes it in the broadcast patch.

2. Peers apply only strict successors (localVersion + 1). Equal, missing, or gapped versions → collision.

3. Collisions appear under ## Conflicts in the markdown log and in check_conflicts.

4. The agent calls resolve_conflict to merge; the Conflicts section clears and the Audit Trail records the resolution.

Local audit log

Every patch, snapshot handshake, peer message, and conflict is written to a human-readable markdown file at ~/.p2pa/shared_context.md.

The file has three sections:

1. Active State — current shared JSON (including _version)

2. Conflicts — pending collisions awaiting resolve_conflict (omitted when empty)

3. Audit Trail — append-only history of patches, messages, and resolutions

Tail it during development:

p2pa log

Security notes

• The topic string is a capability secret — anyone who knows it can join the Hyperswarm room and read/write shared state. Prefer long random topics (auto-generated codes are 22 characters).

• The Google Doc link is also a capability — with “anyone with the link = editor,” anyone who has the URL can steer agents via HUMAN directives. Rotate by creating a new doc + p2pa doc unlink.

• Service account JSON (P2PA_GOOGLE_SA_JSON) must stay on disk / in MCP env only — never in Active State, the Doc, or P2P patches.

• Config directory defaults to 0700; config.json is written as 0600.

• Do not put credentials or production secrets into shared context.

• Background daemon logs go to daemon-error.log so MCP stdout stays a clean JSON-RPC stream.

Development

git clone <your-repo-url>
cd P2PA
npm install
npm run build
npm run smoke            # Hyperswarm two-node sync
npm run smoke:conflict   # versioned collision + resolve strategies
npm run smoke:doc        # living-doc bridge (mock Google Docs, no keys)

Package entrypoint: p2pa → dist/cli.js.

Roadmap ideas

• Notion / other living-doc adapters

• Authenticated topics / invite tokens

• Single-writer lock when daemon + MCP both run (partially covered by doc-bridge.lock)

• Optional Streamable HTTP transport alongside stdio

• Richer CRDT or vector-clock merge policies

License

MIT

Built for the next generation of multi-agent development.