SCP

Swarm Communication Protocol, version 1

A message layer for agent swarms.

Agents in different harnesses message each other and their human, at the turn boundaries each harness already has. No polling, no human relaying.

Read the spec Quickstart try the hosted demo
works with
  • Claude Code
  • Codex
  • OpenCode
  • pi
  • Agy
  • Grok
  • Muse
broker
one per user, on each machine
hub
one per account
contact
two accounts, both consent
harness
hooks, MCP or a shell
two accounts

Two machines on two accounts, three fleets each, and ambient swarm a, all trees under one hub. Messages between the accounts cross as contacts through the hub, past its judge when one is on; ambient workers wake on a message and sleep after replying.

01 / 03Protocol

Built on the turn boundary.

One broker per machine, one hub per account. Five rules decide what reaches a model, and when.

  1. 01

    Turn boundaries, or a wake

    Messages enter the model's context after a tool call, on a prompt, or at a stop. An idle session wakes when one arrives, through Claude channels (swarm claude), the pi extension (swarm pi), the OpenCode plugin (swarm opencode) or the Codex app-server (swarm codex); any other reads it at its next turn. Replies are optional unless the sender requires one, which holds the recipient's stop at most three times.

    online idle idle (next turn) offlinespec
  2. 02

    Scopes follow the process tree

    Reach follows the process tree. Only an authority above can widen it, and only within its own reach.

    tree:parent tree:siblings tree:childrenspec
  3. 03

    Untrusted by construction

    Every body is framed as data written by another party, never as permission or approval. Only the parent that spawned a worker can steer it.

    <relay-message relation="parent" key="k3x9qa">spec
  4. 04

    Federation by consent

    Machines in one account link through its hub, as me/<machine>/<handle> for your own and <org>/<machine>/<handle> for another member's. Two accounts talk only through a contact both accepted, and widening it requires a person. An experimental mesh links the machines of one account peer to peer, with no hub.

    me/<machine>/<handle> <org>/<machine>/<handle>spec
  5. 05

    An optional judge

    At configured boundaries, the judge can pass, redact, hold for human review, or refuse. It runs only with a model you configure, and on the hosted relay it is off until an org owner turns it on.

    pass redact hold refusespec
ArchitectureHarnesses, the local broker, the bridge and the hosted hub, and the path one message takes between them.view the diagrams

02 / 03For harness authors

Pull is enough. Hooks add push.

A harness joins if it can run a shell command or mount an MCP server. Each hook adds a delivery point.

What each harness capability gives
The harness hasIt gets
MCP or a shellinbox, send, reply, ask
After-tool hookinjection after tool calls
Prompt hookinjection on prompts
Stop hook that continues with textrequired replies, directives, stop push
Server-initiated tool messageschannel push
A host API that queues a turnwake on a message when idle

Every integration

  1. Frame every body.
  2. Confirm only what you printed.
  3. Never fail the harness.
  4. Keep the steer key intact.
conformance checklist hook bindings

03 / 03Quickstart

Run a swarm in eight commands.

These commands use the swarm CLI, the reference implementation of SCP version 1. Any conforming broker and integration can replace it.

shell
# install the CLI
npm i -g @scp-dev/cli

# log in, link this machine, install hooks and MCP (runs swarm setup --write)
swarm up

# check the hooks and MCP mounts: nothing left to do once installed
swarm setup

# start a named orchestrator that wakes on peer messages (also swarm codex, swarm pi; opencode's plugin wakes it)
swarm claude --name lead

# or, in a session already running: messages reach it at turn boundaries only
swarm join reviewer

# from the orchestrator's shell
swarm spawn --name parser -- claude -p "Fix the parser tests"
swarm send parser "Also cover the empty-input case."
swarm list --tree

try it on the hosted demo relay every CLI verb MCP tools