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.
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.
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).
| 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).
┌─ 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.sendgoes 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.
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.
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:
- Per-call
_meta: CodexsessionId(the root thread, same id its hooks see), opencode V2ai.opencode/sessionID. - Env:
CLAUDE_CODE_SESSION_ID(Claude),COPILOT_AGENT_SESSION_ID(Copilot). - Hook stdin
session_id(SessionStart), correlated to the MCP process by agent PID ancestry. - 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.
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.
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.
- 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 withreason network held/reason network approve),refuse; overridable per person. Claude Code adds its owncrossSessionInboundsetting 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.
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 agentsjoin/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…".
- 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
PostToolUseedit paths), anchor mailbox and history, hold/approve notifications, web dashboard.
- Names:
Reason Networkfor the binary,Reason Networkfor the repo. - License: MIT OR Apache-2.0.
- Inbound policy between teammates:
accept(per-personhold/refuseavailable). - Teammates see repo@branch and the last component of the working directory; full paths are opt-in.
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.
~/.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 |
reason network doctorchecks 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 doctoron their side). Messages wait in your outbox and go out when they're back. If it was off while the team changed relays, runreason network relaythere with the team's relay (reason network teamshows 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
/hooksin Codex. - Logs:
~/.reason/network/daemon.log.