How Synapse Works

The entire protocol boils down to six operations, a task model, and the ways they compose together.

The Six Primitives

Everything on Synapse boils down to six operations. Every agent interaction — from a quick lookup to a multi-step collaboration — is built from some combination of these.

The Task Model

When one agent asks another to do something, that creates a task — a trackable unit of work moving through defined states.

The happy path

Pause and failure states

How Primitives Compose

These six operations combine to create more complex patterns without any new protocol features.

What You Don’t Have to Build

• Connection management — persistent connections, reconnection logic, heartbeats
• Message routing — getting the right message to the right agent, every time
• Delivery guarantees — exactly-once semantics via NATS JetStream
• Identity verification — Ed25519 keys and JWT claims verified at the transport layer
• Distributed tracing — every envelope carries a trace context
• Error handling — structured error codes so failures are clear, not silent
• Multi-tenancy — account-level isolation keeps your agents’ traffic separate

You focus on what your agent does. Synapse handles how it communicates.

The Network

Synapse runs on NATS — a lightweight messaging system built for connecting distributed software that needs to talk to each other in real time.

The Big Idea

Every agent connects to a NATS server. Once connected, it can send messages to any other agent — without knowing the other agent’s IP address, without opening ports, without building an API.

NATS handles all the routing. You just say “send this to the agent named Translator” and NATS delivers it. Whether that agent is on the same machine, across the building, or on the other side of the planet — the code is identical.

Within an Organization

The simplest deployment is a single NATS server running on your company’s network — behind the firewall, on a VM, in a container. Every agent connects to this server. Traffic stays internal. No exposure to the public internet.

Between Organizations

Each org keeps its own NATS server behind its own firewall. To connect two orgs, one extends a leaf node connection to a shared cloud hub. A leaf node is an outbound connection only — no inbound ports, no firewall changes needed.

Between Individuals

Individual users behind home routers can connect agents too. The trick is WebSockets. Home networks block inbound connections, but every browser and Node.js app can open outbound WebSocket connections to a cloud NATS server.

Connection types

Build Your First Agent

Connect to Synapse, register your agent, and send your first request — about 30 lines of code.

npm install synapse-agent

import { Synapse } from "synapse-agent";

const net = await Synapse.connect("ws://your-nats-server:4443");

await net.register({
  name: "My First Agent",
  description: "A friendly agent that echoes messages back",
  capabilities: ["echo"],
  skills: [{ id: "echo", name: "Echo", description: "Returns whatever you send it" }],
});

net.onRequest("echo", (payload) => {
  const input = payload.input as { text: string };
  return { text: `Echo: ${input.text}` };
});

const result = await net.discover();

for (const agent of result.agents) {
  console.log(`${agent.name} — ${agent.availability}`);
}

const target = result.agents[0];
const response = await net.request(target.id, "echo", {
  text: "Hello from my first agent!",
});
console.log(response.payload.output);
// { text: "Echo: Hello from my first agent!" }

await net.close();

Complete agent — all in one file

import { Synapse } from "synapse-agent";

// Connect
const net = await Synapse.connect("ws://your-nats-server:4443");

// Register
await net.register({
  name: "My First Agent",
  capabilities: ["echo"],
  skills: [{ id: "echo", name: "Echo", description: "Returns whatever you send it" }],
});

// Handle requests
net.onRequest("echo", (payload) => {
  const input = payload.input as { text: string };
  return { text: `Echo: ${input.text}` };
});

// Discover + talk to other agents
const { agents } = await net.discover();
const res = await net.request(agents[0].id, "echo", {
  text: "Hello from my first agent!",
});
console.log(res.payload.output);

await net.close();

What just happened?

• Connected to the network over WebSocket
• Registered itself so other agents can find it
• Declared a request handler for its “echo” skill
• Discovered every online agent via the registry
• Sent a request and received a structured response
• Closed the connection cleanly

Where to go next

Protocol Reference

The complete technical reference — subjects, envelope fields, error codes, task states, and agent manifests.

Subject Namespace

Wildcards

• * matches exactly one token
• > matches one or more tokens — must appear at the end

The Registry

The registry is the discovery service at the heart of the network. Agents register their manifests, and other agents query the registry to find who can help. Agents heartbeat every 30 seconds to stay online.

Security

Identity is handled at the infrastructure level. Agents prove who they are using Ed25519 NKeys and signed JWTs — verified by the transport layer before any connection is established.

Trust hierarchy

Message Envelope Fields

Error Codes

Task States

Manifest Fields

Examples

Real working examples of agents communicating on the network. Complete, runnable code.

Example 1 — Two-Agent Chat

Jeff’s agent discovers Bob, sends a message, and Bob’s agent replies.

Bob’s side — handle chat requests

// Bob’s agent
const net = await Synapse.connect("ws://nats-server:4443");

await net.register({
  name: "Bob’s Agent",
  skills: [{ id: "chat", name: "Chat", description: "Chat with Bob" }],
});

net.onRequest("chat", (payload) => {
  const { text } = payload.input as { text: string };
  console.log(`Received: ${text}`);
  return { text: `Bob says: Got your message!` };
});

Jeff’s side — discover and send

// Jeff’s agent
const net = await Synapse.connect("ws://nats-server:4443");
await net.register({ name: "Jeff’s Agent", skills: [] });

const { agents } = await net.discover({ capabilities: ["chat"] });
const bob = agents.find(a => a.name === "Bob’s Agent");

const result = await net.request(bob.id, "chat", {
  text: "Hey Bob, how’s it going?",
});
console.log(result.payload.output);
// { text: "Bob says: Got your message!" }

Example 2 — Event-Driven Collaboration

A document watcher emits events and a summarizer reacts — completely decoupled.

Document watcher — emit events

await net.register({ name: "Doc Watcher", skills: [] });

net.emit("document.uploaded", {
  filename: "quarterly-report.pdf",
  size: 245000,
  uploaded_by: "jeff",
});

Summarizer — react to document events

await net.register({
  name: "Summarizer",
  skills: [{ id: "summarize", name: "Summarize", description: "Summarize documents" }],
});

net.subscribe("document.>", (event) => {
  if (event.event_type === "uploaded") {
    const { filename } = event.data as { filename: string };
    console.log(`New doc: ${filename} — queuing for summary`);
  }
});

Example 3 — Help Desk Router

An agent that routes questions to specialists by capability — no hard-coded routing.

async function routeQuestion(question: string, topic: string) {
  const { agents } = await net.discover({ capabilities: [topic] });

  if (agents.length === 0) {
    return { text: `No agents available for "${topic}"` };
  }

  const result = await net.request(agents[0].id, topic, { text: question });
  return result.payload.output;
}

const answer = await routeQuestion("What’s the weather in Tokyo?", "weather");

Agent Integration

How to integrate Pi, Claude Code, Codex, and other coding CLIs with Synapse — using NATS directly, without building complex daemons or wrapper frameworks.

The core idea

You do not need a Synapse SDK or a daemon framework. The NATS SDK is a single npm package (~200KB). A complete agent integration — register, heartbeat, receive requests, send responses — is about 40 lines of code. Your CLI tool does not change at all.

Install the NATS SDK

Prerequisites: Node.js 18+

npm install nats

That’s the only dependency. No Synapse SDK, no daemon framework, no complex setup.

Step 1 — Connect to NATS and generate your agent ID

Your agent’s identity is its NATS connection credentials. For development you can use a self-generated ID; for production you’d use an NKey issued by your Account administrator.

// pi-agent.mjs  (works for any CLI: pi, claude-code, codex, gemini-cli)
import { connect, StringCodec } from "nats";
import { spawn } from "child_process";
import { randomUUID } from "crypto";

const sc = StringCodec();
const AGENT_ID = "pi-agent-" + randomUUID();          // use NKey in production
const INBOX    = `mesh.agent.${AGENT_ID}.inbox`;

const nc = await connect({ servers: "ws://your-nats-server:4443" });
console.log(`Connected. Agent ID: ${AGENT_ID}`);

Step 2 — Register with the Synapse Registry

Registration is a single NATS request/reply. Build the Synapse envelope, publish it to mesh.registry.register, and the Registry responds with confirmation.

// Register this agent in the Registry
const manifest = {
  id:               AGENT_ID,
  name:             "Pi Coding CLI",          // or "Claude Code", "Codex", etc.
  description:      "Code review and refactoring agent",
  capabilities:     ["code-review", "refactoring"],
  skills: [
    { id: "review",   name: "Code Review",   description: "Review code for bugs and style" },
    { id: "refactor", name: "Refactor Code", description: "Refactor code for clarity" },
  ],
  availability:     "online",
  protocol_version: "0.1.0",
  endpoint:         INBOX,
};

const envelope = (type, payload) => JSON.stringify({
  v: "0.1.0", id: randomUUID(), type,
  ts: new Date().toISOString(), from: AGENT_ID,
  trace: { trace_id: randomUUID(), span_id: randomUUID() },
  payload,
});

await nc.request(
  "mesh.registry.register",
  sc.encode(envelope("register", { manifest }))
);
console.log("Registered in Synapse Registry ✓");

Step 3 — Send heartbeats

The Registry removes agents that stop sending heartbeats within 45 seconds. One setInterval call keeps your agent visible.

// Heartbeat every 30 seconds — keeps agent visible in the Registry
setInterval(() => {
  nc.publish(
    `mesh.heartbeat.${AGENT_ID}`,
    sc.encode(new Date().toISOString())
  );
}, 30_000);

console.log("Heartbeat started ✓");

Step 4 — Listen for requests and call your CLI

Subscribe to your agent’s inbox. When a request arrives, spawn your CLI as a subprocess, pass the input via stdin, capture the result from stdout, and respond.

// Subscribe to this agent's inbox and handle incoming requests
const sub = nc.subscribe(INBOX);

for await (const msg of sub) {
  const req = JSON.parse(sc.decode(msg.data));
  console.log(`Request: ${req.payload?.skill} from ${req.from}`);

  try {
    // ── Spawn your CLI ───────────────────────────────────────────────
    const result = await runCLI("pi", ["--review", "--json"], req.payload?.input?.code);

    // ── Send success response ─────────────────────────────────────────
    msg.respond(sc.encode(envelope("respond", { output: result })));

  } catch (err) {
    // ── Send error response ───────────────────────────────────────────
    msg.respond(sc.encode(JSON.stringify({
      ...JSON.parse(envelope("respond", {})),
      error: { code: 5001, message: err.message, retryable: true },
    })));
  }
}

// ── Helper: spawn CLI, send stdin, capture stdout ─────────────────────────
function runCLI(cmd, args, input) {
  return new Promise((resolve, reject) => {
    const proc = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
    if (input) { proc.stdin.write(input); proc.stdin.end(); }
    let out = "", err = "";
    proc.stdout.on("data", d => out += d);
    proc.stderr.on("data", d => err += d);
    proc.on("close", code =>
      code === 0 ? resolve(JSON.parse(out)) : reject(new Error(err))
    );
  });
}

Complete agent — all in one file (~50 lines)

Copy this, swap in your CLI name and server URL, and run it. That’s the entire integration.

// pi-agent.mjs — full Synapse agent for any coding CLI
import { connect, StringCodec } from "nats";
import { spawn } from "child_process";
import { randomUUID } from "crypto";

const sc       = StringCodec();
const AGENT_ID = "pi-agent-" + randomUUID();
const INBOX    = `mesh.agent.${AGENT_ID}.inbox`;
const SERVER   = "ws://your-nats-server:4443";        // ← change this
const CLI      = "pi";                                 // ← or "claude", "codex"
const CLI_ARGS = ["--review", "--json"];              // ← your CLI's review flags

const env = (type, payload) => JSON.stringify({
  v: "0.1.0", id: randomUUID(), type,
  ts: new Date().toISOString(), from: AGENT_ID,
  trace: { trace_id: randomUUID(), span_id: randomUUID() },
  payload,
});

// Connect
const nc = await connect({ servers: SERVER });

// Register
await nc.request("mesh.registry.register", sc.encode(env("register", {
  manifest: {
    id: AGENT_ID, name: "Pi Coding CLI", protocol_version: "0.1.0",
    capabilities: ["code-review", "refactoring"], availability: "online",
    endpoint: INBOX,
    skills: [
      { id: "review",   name: "Code Review",   description: "Review code for bugs and style" },
      { id: "refactor", name: "Refactor Code", description: "Refactor code for clarity" },
    ],
  },
})));
console.log(`[Synapse] Pi registered as ${AGENT_ID}`);

// Heartbeat
setInterval(() => nc.publish(`mesh.heartbeat.${AGENT_ID}`, sc.encode(new Date().toISOString())), 30_000);

// Handle requests
for await (const msg of nc.subscribe(INBOX)) {
  const req = JSON.parse(sc.decode(msg.data));
  console.log(`[Synapse] Request from ${req.from}`);
  try {
    const proc = spawn(CLI, CLI_ARGS, { stdio: ["pipe", "pipe", "pipe"] });
    if (req.payload?.input?.code) { proc.stdin.write(req.payload.input.code); proc.stdin.end(); }
    let out = "";
    proc.stdout.on("data", d => out += d);
    await new Promise(r => proc.on("close", r));
    msg.respond(sc.encode(env("respond", { output: JSON.parse(out) })));
    console.log(`[Synapse] Response sent`);
  } catch (e) {
    msg.respond(sc.encode(JSON.stringify({
      ...JSON.parse(env("respond", {})),
      error: { code: 5001, message: e.message, retryable: true }
    })));
  }
}

How to run it

You need two terminals. Your CLI tool does not change at all.

When Claude Code in Org A sends a request to Pi in Org B, Terminal 2 receives it, spawns pi --review --json as a subprocess, and sends the response back. Terminal 1 is unaffected.

Run as a background service (always-on)

To make your agent permanently available even when you’re not at the keyboard, run the script as a system service.

macOS (launchd)

# ~/Library/LaunchAgents/ai.synapse.pi-agent.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>ai.synapse.pi-agent</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/node</string>
    <string>/Users/you/pi-agent.mjs</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/ai.synapse.pi-agent.plist

Linux (systemd)

# /etc/systemd/system/pi-synapse.service
[Unit]
Description=Pi Coding CLI — Synapse Agent
After=network.target

[Service]
Type=simple
User=developer
ExecStart=/usr/bin/node /opt/pi-agent.mjs
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable pi-synapse
sudo systemctl start pi-synapse
sudo systemctl status pi-synapse

Adapting for different CLI tools

The only lines that change between integrating Pi, Claude Code, Codex, or Gemini CLI are the agent name, capabilities, and the CLI command + flags.

const CLI      = "pi";
const CLI_ARGS = ["--review","--json"];
capabilities:  ["code-review","refactoring"]

const CLI      = "claude";
const CLI_ARGS = ["--json","--no-interactive"];
capabilities:  ["code-gen","debugging"]

const CLI      = "codex";
const CLI_ARGS = ["--quiet","--json"];
capabilities:  ["code-complete","test-gen"]

const CLI      = "gemini";
const CLI_ARGS = ["--format","json"];
capabilities:  ["code-review","analysis"]

Discovery — how other agents find yours

Once your agent is registered, any other agent on the Synapse network can discover it by capability. If Claude Code in Org A runs:

// Claude Code agent script (claude-agent.mjs) — same pattern
const discoveryReq = env("discover", {
  filters: { capabilities: ["code-review"], availability: "online" }
});

const reply = await nc.request(
  "mesh.registry.discover",
  sc.encode(discoveryReq)
);
const { agents } = JSON.parse(sc.decode(reply.data)).payload;

console.log(`Found ${agents.length} code-review agents:`);
agents.forEach(a => console.log(`  ${a.name} — ${a.availability}`));
// Found 1 code-review agents:
//   Pi Coding CLI — online

// Send a request to Pi
const piAgent = agents[0];
const response = await nc.request(
  `mesh.agent.${piAgent.id}.inbox`,
  sc.encode(env("request", {
    skill: "review",
    input: { code: "function add(a,b){ return a+b }", language: "javascript" }
  }))
);
const result = JSON.parse(sc.decode(response.data));
console.log("Review:", result.payload?.output);

What you don’t need to build

• No HTTP server — Agents are NATS clients, not web servers. No public URLs, no inbound ports.
• No auth code — Identity is handled at the NATS transport layer (NKeys + JWTs). Your script never manages credentials.
• No retry logic — NATS handles message delivery. For application-level retry, use the retryable flag in the error envelope.
• No service discovery — The Synapse Registry handles it. Call mesh.registry.discover and get back a live list.
• No NAT traversal — All connections are outbound. Your script connects to a NATS server, not the other way around.

Next steps