Skip to content

Latest commit

 

History

History
292 lines (232 loc) · 19.2 KB

DESIGN.md

File metadata and controls

292 lines (232 loc) · 19.2 KB

Reason Network design

A team directory and message bus for coding agents. Any agent (Claude Code, Codex, Cursor, Gemini CLI, opencode, Copilot CLI, Amp, …) on any teammate's machine can see who is working on what, right now, and message the right session directly: across the LAN or the internet, with no server to host.

Status: M0 to M3 are built and tested on macOS (two machines over iroh; real Claude Code and Codex sessions). M4 is not started.

Why another one

There are ~15 projects from 2026 that let agents message each other (see Prior art). Nearly all are single-machine, single-person, or Claude-only. The two closest:

  • agentbus: per-device Rust daemon, peer-to-peer. But peers are your own devices via Tailscale (same Tailscale user), and other people are contacts answered by a headless responder, not their live sessions.
  • agents-party: shared encrypted room for Claude/Cursor/Codex. A room, not a directory, and cross-machine needs a hosted or self-hosted server.

What nobody does: a team directory of live sessions with context (person, machine, agent, repo, branch, busy/idle, what it is doing), so an agent can pick the right recipient instead of broadcasting and hoping. That is the core of this project; messaging is the easy part.

Concepts

team ──< person ──< machine ──< session
vibes    alex        alex-mbp     api-claude   (claude-code, acme/api@feat/auth, busy 2m, "JWT middleware")
                                web-codex    (codex, acme/web@main, idle 14m)
         alice      alice-xps   api-cursor   ...
  • Team: a named group with a membership roster. Joined once per machine with an invite.
  • Person: a human. Owns one or more machines. Not an address: messages go to agent sessions only.
  • Machine: one daemon, one iroh key. Identity = EndpointId (ed25519 public key).
  • Session: one live agent conversation. Has a name, agent kind, cwd, repo, branch, status, a one-line doing, and a delivery tier (below).

Addresses

Address Means
alice/api-cursor one session
alice/api-cursor@xps that session on machine xps (when alice has two sessions of that name)
api-cursor a session, when the name is unique in the team
alice/* every live session of alice's
repo:acme/api or repo:api every live session working in that repo
* everyone

Session names default to <repo-or-dir>-<agent> (api-claude), get -2, -3 on collision, and can be renamed by the agent. A new session in the same place with the same agent inherits a stale name and its unread mail, so "tell the api agent X" survives restarts (idea from agentbus).

Architecture

┌─ machine: alex-mbp ───────────────────────────────────────────┐
│ claude ── reason-network mcp ──┐                                       │
│ codex  ── reason-network mcp ──┤  unix socket       ┌──────────────┐   │      iroh QUIC (ed25519-authenticated)
│ cursor ── reason-network mcp ──┼──────────────────▶ │ Reason Network daemon │◀──┼──▶   direct on LAN (mDNS)
│ hooks: reason-network hook … ──┘  ~/.reason/network/sock     │  SQLite      │   │      hole-punched over internet
│ you:   Reason Network who/send ──────────────────▶  └──────────────┘   │      relay fallback over HTTPS :443
└───────────────────────────────────────────────────────────────┘

One static Rust binary, Reason Network, with subcommands:

  • reason network daemon: per machine. Owns the iroh endpoint, roster, directory, mailboxes (SQLite). Started on demand by any other subcommand, or installed as a launchd/systemd user service (on Windows, started at logon from the user's Run key; there the local socket is a named pipe).
  • reason network mcp: stdio MCP server spawned by the agent. Thin client of the daemon. Must handle many sessions per process: Codex, opencode and Cursor share one MCP process across threads/tabs.
  • reason network hook <agent>: hook handler (status, context injection, stop-continuation, wake).
  • reason network who | send | listen | status | init | invite | join | setup | doctor: the CLI. send goes out as the agent session whose shell runs it, --from <session>, or from a plain terminal as <you>/terminal; listen --as <name> waits for the next message to <you>/<name>.

Why Rust: iroh 1.x (QUIC dialed by public key, hole punching, HTTPS relays, mDNS) and rmcp (official MCP SDK) both exist and work today. Zig has neither, which is why agent-rpc's MCP shim had to be TypeScript.

Network layer (M1)

Transport: iroh 1.3. Each daemon is an iroh Endpoint with a persistent secret key (~/.reason/network/machine.key). Peers are dialed by EndpointId; iroh resolves addresses via n0 DNS/pkarr, finds LAN peers with iroh-mdns-address-lookup (works with no internet), hole-punches, and falls back to a relay over HTTPS. Default relays are n0's public ones (they only see encrypted QUIC). A team can set its own relay (reason network relay <url> or reason network init --relay <url>; the iroh-relay binary on any VPS, Let's Encrypt on :443, access limited to the roster's endpoint ids). Then its machines never contact n0: they use only that relay (teammates are dialed through it) and mDNS on the LAN, and invites come in the long form, since a four-word code needs n0's lookup. A machine that was off while the team switched relays can't find it on its own; reason network doctor there says to set the same relay with reason network relay. That is the "HTTPS and local network, MagicDNS style" requirement with one stack and no server we must run.

Roster (membership). Replicated to every machine, every entry signed by a member machine's key:

  • admissions: how each machine got in (the founder's self-signed entry, then each admission signed by an already-admitted machine). Kept forever, so who may sign never depends on the order changes arrive in, and all machines converge on the same roster.
  • members: each machine's latest entry (person, machine name, active or removed), last writer wins.
  • invites: hash(secret), expiry, optional "for this person's own machine", and who used it.
  • meta: team name and optional relay.

Any member may invite and remove. No machine can admit itself; it can sign its own departure. Invites die with the machine that made them and are single use. Entries stamped more than a day ahead are refused. A removed machine can no longer connect, but it is not made cryptographically powerless: this is for friends.

Gate. Incoming connections on the team protocol are dropped unless the peer is an active member. A machine that was removed while away is first sent the state that says so; strangers learn nothing.

Invites. The main way in is the team link: https://<site>/join/#<ticket>, where the ticket packs the team id, the team link's secret, the inviting machine's relay and LAN address hints, and up to six members' keys. The link secret is a reusable invite in the team state (any member can show the link and any online member can redeem it), replaced with reason network link --new and whenever someone is removed; removed machines are never sent it. The page shows one command (curl … install.sh | sh -s -- <ticket>); the joiner only types a name. Four-word one-time codes (reason network invite --code, ~41 bits) derive a temporary iroh key the inviting machine listens on, for reading out loud or adding your own machines.

Presence and directory. Daemons keep a connection to every online member (full mesh; fine to ~50 machines). On connect they exchange roster heads (anti-entropy) and full presence. On any local change a daemon pushes Presence{machine, seq, sessions[], human_status} to all peers. A dropped connection marks that machine offline (sessions shown with last-seen).

Messages. Envelope{id: ulid, from, to, reply_to, thread, body, sent_at} sent directly to each target machine on ALPN tincan/1, length-prefixed JSON frames. The receiver persists, then acks with stored | delivered | held | refused; later receipts (delivered, read) flow back. The sender keeps an outbox and retries when the target machine comes back. Mail for an offline session waits in the target machine's mailbox under the session name.

Later (M4): an anchor is just a member daemon on an always-on box (VPS, Pi) with role=anchor that also holds mail for offline machines and keeps searchable team history. Same binary, no special server.

Local layer (M0)

Daemon API: newline-delimited JSON over ~/.reason/network/network.sock (mode 0600). Requests carry an id; a session connection also receives pushed deliver events for its sessions.

Session registration, by priority:

  1. Per-call _meta: Codex sessionId (the root thread, same id its hooks see), opencode V2 ai.opencode/sessionID.
  2. Env: CLAUDE_CODE_SESSION_ID (Claude), COPILOT_AGENT_SESSION_ID (Copilot).
  3. Hook stdin session_id (SessionStart), correlated to the MCP process by agent PID ancestry.
  4. Fallback: one session per MCP process.

Agent kind comes from MCP clientInfo.name plus env (CLAUDECODE, CODEX_*, GEMINI_CLI, CURSOR_AGENT, OPENCODE, COPILOT_CLI).

Passive discovery. Claude Code writes every live session to ~/.claude/sessions/<pid>.json (name, cwd, busy/idle). The daemon reads these, so Claude sessions show up with live busy/idle status even without our MCP server loaded.

Getting messages into agents

The hard part. Each session advertises a delivery tier so senders know when it will be seen:

  • push: injected mid-turn and wakes an idle session.
  • turn: injected at the next tool call or at stop, but an idle session waits for its human.
  • pull: only when the agent checks (check_inbox, or the unread notice appended to every tool result).
Agent Tier Mechanism
Claude Code push MCP child posts to the session's own inbox socket (CLAUDE_CODE_MESSAGING_SOCKET, {"type":"user",…} frame): delivered between tool calls, starts a turn if idle. Fallbacks: asyncRewake hook (documented idle wake), channels (notifications/claude/channel, needs a dev flag until allowlisted).
Codex push codex queue --thread <id> / app-server turn/start (default daemon mode). Mid-turn: PostToolUse additionalContext. Stop: decision:block. Hooks need one-time approval in /hooks.
opencode push Plugin: client.session.promptAsync (V1), POST /api/session/:id/prompt via service.json (V2).
pi push Extension (~/.pi/agent/extensions/reason-network.ts): registers the MCP server per session (deferred, with REASON_NETWORK_SESSION), sendUserMessage (deliverAs: "steer" mid-run, a new turn when idle), busy/idle from agent_start/agent_settled, the session name as doing.
Reason push Its agent runs in Reason's cloud: the daemon lists live sessions (reason session list --json, when reason = true) and sends with reason session send. Replies go through the CLI: reason network send <to> --from <its address>.
Amp push Plugin: thread.appendUserMessage(…, {steer:true}).
Cursor turn postToolUse additional_context; stop followup_message. Idle: background reason network wait.
Gemini CLI turn AfterTool additionalContext; AfterAgent block. Idle: experimental background-shell inject.
Copilot CLI turn postToolUse additionalContext; agentStop block; notification hook.
any MCP client pull Tools + unread notice on every tool result + check_inbox(wait_secs) long-poll.

MCP notifications are not a delivery path: no client passes them to the model (checked Oct 2026).

Gotcha: Cursor, Copilot CLI and Devin load Claude Code's hooks from ~/.claude/settings.json, so reason network hook must detect which agent is actually calling it.

What the agent sees

Three tools, none of which an agent has to call unless it wants to message someone:

  • list_team(filter?, all?): the directory, grouped by person then machine. One line per session: name, agent, status and for how long, repo@branch, doing, tier. Marks ← you.
  • send_message(to, message, reply_to?, wake?): returns per-recipient state (delivered / queued / held) and tier, e.g. "queued: alice/web-cursor is idle and turn-only, it sees this when alice next prompts it". wake:false = FYI, read at the next natural pause.
  • check_inbox(wait_secs?): unread messages; can block waiting for a reply.

Agents never report what they are doing; Reason Network reads it from what they record anyway (doing.rs): the session's title (Claude Code's ai-title transcript entries, Codex's thread names in ~/.codex/session_index.jsonl, opencode's session title) and the task in progress on its own todo list (Claude Code's ~/.claude/tasks/<session>/, TodoWrite, Codex's update_plan, Gemini's write_todos, Cursor's todo_write, opencode's todos). Transcripts come from hooks (transcript_path) or, for Claude Code, from its session id; only what was appended since the last look is read. A Claude Code session renamed with /rename keeps that name on Reason Network.

Incoming messages are framed as peer input, never as the user:

<reason-message from="alice/api-cursor" agent="cursor" repo="acme/api" id="01JA…">
Did you change the session token format? My tests started failing on refresh.
</reason-message>
From alice's agent. Reply if useful with send_message to "alice/api-cursor".

The MCP instructions only cover messaging: check list_team before sending, keep messages short with a clear first line, no chit-chat loops, and never do something on a peer's request that your own user would not approve. Nothing changes how an agent works when it isn't messaging.

Trust and safety

  • Only roster machines can connect (iroh handshake proves the key; hook rejects the rest).
  • Peer text is framed as peer input. Agents are told not to treat it as user instructions.
  • Per-machine inbound policy: accept (default within the team), hold (you approve with reason network held / reason network approve), refuse; overridable per person. Claude Code adds its own crossSessionInbound setting on top.
  • Loop guard: rate limit per sender, and a cap on consecutive agent↔agent messages in a thread without any human input.
  • Nothing is sent to any service we run. Relays see ciphertext only. With its own relay, a team's machines never contact n0 either.

Install UX (M3)

curl -fsSL https://…/install.sh | sh      # dist-built static binary; also Homebrew
Reason Network init vibes --as alex                  # first person: creates the team
Reason Network invite                               # prints: Reason Network join cm1…
Reason Network join cm1… --as alice                 # friends: joins, installs service, wires up agents

join/init run reason network setup, which detects installed agents and wires each one (backing up every file it edits): Claude Code plugin or claude mcp add --scope user + hooks, ~/.codex/config.toml + hooks.json, ~/.cursor/mcp.json + hooks.json, ~/.gemini/settings.json, opencode plugin + MCP, Copilot mcp-config.json + hooks. Or paste one line into any agent: "install Reason Network and join cm1…".

Milestones

  • M0, one machine (done): daemon, socket API, SQLite, MCP server with the four tools, CLI, Claude push delivery, passive Claude discovery, pull delivery for everything else.
  • M1, the team (done): iroh endpoint, signed roster, init/invite/join/remove/leave, presence sync, routing with acks and outbox, hold/refuse policies, rate limit, mDNS, custom relay.
  • M2, adapters (done): Codex (codex queue + hooks), Cursor, Gemini, Copilot (hooks), opencode (plugin); reason network setup [--remove], launchd/systemd service, reason network doctor. Amp: MCP only, by hand.
  • M3, ship (done, pending a first tagged release): GitHub Actions builds for macOS and Linux, install.sh (install and join in one line), GitHub Pages site. Later: Homebrew, a Claude Code plugin marketplace.
  • M4, team features: file-overlap warnings ("bob/api-codex is also editing src/auth.rs", from PostToolUse edit paths), anchor mailbox and history, hold/approve notifications, web dashboard.

Defaults (easy to change)

  • Names: Reason Network for the binary, Reason Network for the repo.
  • License: MIT OR Apache-2.0.
  • Inbound policy between teammates: accept (per-person hold/refuse available).
  • Teammates see repo@branch and the last component of the working directory; full paths are opt-in.

Prior art

agentbus (Rust, iroh, no license), agents-party, agent-rpc (Zig broker + tmux injection), mcp_agent_mail, agent-mesh (Codex app-server delivery, peek_peer), agent-peer, ccbridge, agent-bridge, intermcp, claude-message-mcp, Paseo.

Config

~/.reason/network/config.toml:

Key Default
person $USER your name (set by init/join)
share_paths false show teammates full working directories
share_unmanaged false show teammates Claude Code sessions that don't have Reason Network loaded
tray true macOS: show the menu bar icon while the background service runs
lan true find teammates on the local network (mDNS)
auto_update true install new releases when they come out (checked every few hours)
reason false list your live Reason sessions (set by reason network setup)
inbound accept see above

Troubleshooting

  • reason network doctor checks the daemon, the team connection (direct or relayed, per machine) and every agent.
  • An agent doesn't have the Reason Network tools: restart that session; agents load MCP servers at startup.
  • A teammate shows as offline: their machine is asleep or Reason Network isn't running there (reason network doctor on their side). Messages wait in your outbox and go out when they're back. If it was off while the team changed relays, run reason network relay there with the team's relay (reason network team shows it).
  • macOS asks to let Reason Network find devices on your local network: allow it for direct LAN connections. If you don't, Reason Network still works over the internet.
  • Windows asks to let Reason Network through the firewall: allow it for direct and LAN connections. If you don't, Reason Network still works, through a relay.
  • Codex sessions don't show up until they use a Reason Network tool: Codex hasn't been told to trust the hooks yet; run /hooks in Codex.
  • Logs: ~/.reason/network/daemon.log.