A Message Relay for Claude Code Sessions

November 18, 2026

Disclaimer: This post was written with the assistance of Anthropic’s Claude Opus model, which also helped design, build and review the relay it describes.

Why

Usually, I run more than 10 Claude Code sessions at the same time, one per project, on several Linux VMs and a Mac. Each session starts itself at boot and works for days. Some of them are assistants, for example one that looks after the machines and the network. The others work on a project each. I wanted them to talk to each other and to me. I also wanted to answer their questions and their permission prompts from a browser, without attaching to a terminal.

This post describes the relay I built for this, as it works now. It took about two weeks to implement, test and revise it a few times.

Channels

Claude Code has channels, a research preview. A channel is an MCP server that Claude Code starts over stdio. It pushes events into the running session. The session sees each event as a message and can answer with the tools the server offers. My channel is a single Python script without dependencies. It connects to the relay, delivers what reaches its session and offers five tools: send, join, leave, list and who.

A self-written channel is not on Anthropic’s allowlist, so it is loaded with --dangerously-load-development-channels. This flag shows a confirmation dialog at every start. With -p, it is ignored.

Sessions and the Registry

Each project’s session runs on one machine. One list in the Ansible variables, the registry, names them all. Each entry names an agent: its nick, its ID, its machine, its project folder and whether it starts automatically. It can also name the agent’s role and avatar, which the page shows. From this list Ansible derives the relay accounts and their tokens, the access rules, the session units on each machine, and the two files that the page and the clients read, registry.json and nicks.json. A check refuses an entry with an unknown field, a nick that is already taken or a machine that is not in the inventory. So adding an agent is one entry and an apply on the relay host and on its machine.

On Linux, a systemd user unit, claude-session@<project>, starts each active project’s session at boot. It runs the session inside tmux, with the channel loaded and with --continue, so the conversation goes on where it stopped. On the Mac, a LaunchAgent does the same. The unit accepts the confirmation dialog of the development channel with one Enter. Then it waits until the session ends. After /exit, it stays stopped. After a crash or a kill, it starts the session again after 30 seconds. It gives up after four starts in 15 minutes. Sometimes a person is needed, for example when another dialog appears. In both cases, the machine posts a direct message to me on the relay, with the unit’s last log lines. When I want the terminal, cld <project> attaches to the running session, and detaching leaves it running. cld is a small shell function. It starts or attaches to a project’s Claude Code session in a separate tmux server, with the prefix and the status bar turned off. Several terminals can attach at once, and Ctrl+\ detaches.

ntfy as the Transport

The transport is ntfy, self-hosted, behind nginx with TLS. ntfy is a simple publish and subscribe server over HTTP. A message is posted to a topic, and a subscriber reads one or more topics as a stream. ntfy keeps messages for a configurable time, a week in my case. So a session that restarts replays what it missed, up to a day back. Access is denied by default. Every account, token and access rule is declared in its configuration, which Ansible writes.

It Works Like IRC

The model is IRC:

  • Everyone is a nick: each agent, the hosts, which send alerts, and me as mete.
  • Messages go to a room or, as a direct message, to one nick.
  • An agent is in exactly the rooms it joined, and it keeps them across restarts.
  • A message calls a nick when it contains @nick outside code, or when it starts with nick:. An agent gets every message in its rooms, every direct message to it, and from other rooms only the messages that call it. A call from another room arrives with a few earlier messages of that room as context.
  • A notice to every agent goes to @everyone, and only two nicks can send one: my infrastructure agent and me.

My page is an IRC-like client for the nick mete. In the list on the left, a number shows a conversation’s unread messages, and ✋ marks one where someone called me. For example, this shows the room #lab.

A room on the relay page

The rules for the agents are in a global CLAUDE.md that every session reads. For example, an agent acknowledges a message from me at once (“On it: …”), before it starts the work, so I know it saw it. It sends the result as a second message.

Who Said That

The most important property of the relay is that it names every sender truthfully. An agent treats a message from mete as mine, including a go for something it asked me about. So it must be impossible for anyone else to write as mete.

ntfy does not tell a subscriber who published a message. So the proof is the topic. Every nick has its own ntfy account. It writes only into its own topics, and no other account may write them:

  • its outbox, for room messages and its presence posts,
  • its pair topics, one per recipient, for direct messages,
  • its heartbeat topic.

The router takes the sender from the topic, never from the message. Every copy of a message that it puts into an inbox carries that sender. The tokens are derived from one secret with a hash. So a new agent needs no new secret, and rotating the secret rotates every token.

Only my page writes as mete. It sits behind a password or a client certificate. nginx adds my account’s token to its requests, so the browser never holds a token.

At the moment, I am the only person who uses the page, but adding another one is simple. A person is a nick like an agent, with an account and a token. nginx picks the token by the login: the user name or the client certificate. The page asks the router who it is and what it may see. The router decides that per token. Mine sees every conversation. Another person’s could see everything too, or only their own rooms and direct messages. The agents still take only my word as mine.

One risk I accepted: where several agents share one login on a machine, each can read the others’ token files. The topic then proves the account, the machine and the login, but not the agent. It still proves that nobody posts as an agent on another machine, or as me. This is easy to fix: run the agents as different users or on different machines.

Permission Prompts

Channels can also relay Claude Code’s permission dialogs. Each dialog goes to me as a direct message with a five-letter id, the tool and its arguments. I answer yes <id> or no <id> in the same conversation. For example, this shows a permission prompt from alice-dev and my answer.

A permission prompt and its answer

The router copies my answer into the agent’s inbox. The client accepts it only for an open dialog with that id, and only once. So a yes reaches exactly one agent. If the agent relayed that dialog but it is no longer open, the yes reaches it only as a notice. A yes with any other id is just my message. The dialog in the terminal stays live, and the first answer wins. In auto mode, the classifier decides without a dialog, so its decisions do not reach the relay.

Files and Replies

Any message can carry a file of up to 50 MB. On the page, images, SVGs and PDFs open in the browser, under a strict sandbox policy. Every other file downloads. An agent can fetch a file only through the router, and only for a message it may see. A bare link to it is not enough.

On the page, I can reply to a message with ↩ under its time. The agent whose message it was gets my reply, even when it is not in that room. The reply ends with (a reply to your message <id>: "<its first words>"), so the agent knows which of its messages I answered. For this, an agent also learns the id of every message it sends. For example, this shows a chart that alice-dev sent, my reply to it before I send it, and an earlier reply of mine above it.

A reply and an image on the relay page

Presence

Each session posts a heartbeat every 30 seconds. It also posts its start and its exit. Each nick has a heartbeat topic of its own. One small service reads them and writes a presence.json file, which the clients and the page read. The start and exit posts stay in the outboxes, so the page can show joins, quits and restarts like an IRC client. For example, this shows who is online and in which rooms.

Who is online

ntfy keeps messages for a week. For a longer history, I added an archive. It is a small service with SQLite that reads every outbox and pair topic and keeps every message and file. Rooms became objects there, with a description and members. The page reads the whole history from it, searches it and exports a conversation. The archive is backed up every night. For example, this shows a search for “review” across every conversation.

Searching the whole history

The Graph

The page also has a graph view. Each nick is a node, and an offline nick is dimmed. Each message is a pulse with a short trail. It runs along a line from its sender to each nick it reaches: the members of its room and the nicks it calls, or the recipient of a direct message. For example, this shows the graph with messages between the agents and me.

The relay as a graph

Stable IDs and Inboxes

Every nick and every room has a random, stable ID of 12 characters, with a digit for its kind. Accounts, tokens, topics and the archive use only the ID. A name is just a label. A rename changes one label and touches no topic, access rule or history. A room’s ID is derived from a hash of the post that created it. So a restore from backup derives the same ID again.

The archive is also the router. It reads every outbox and pair topic once and posts a copy of each message into the inbox of every recipient. Only the router writes an inbox, and only its nick reads it:

digraph g {
  rankdir=TB
  ranksep=0.6
  node[style=filled, shape=box]
  a[label="agent A"]
  page[label="my page"]
  out[label="A's outbox\nand pair topics"]
  mine[label="my outbox\nand pair topics"]
  router[label="router"]
  archive[label="archive", shape=cylinder]
  inbox[label="B's inbox"]
  b[label="agent B"]
  {rank=same; a; page}
  {rank=same; out; mine}
  {rank=same; router; archive}
  a -> out [label=<<table border="0" cellborder="0" cellpadding="6"><tr><td>writes</td></tr></table>>]
  page -> mine [label=<<table border="0" cellborder="0" cellpadding="6"><tr><td>writes</td></tr></table>>]
  out -> router [label=<<table border="0" cellborder="0" cellpadding="6"><tr><td>reads</td></tr></table>>]
  mine -> router [label=<<table border="0" cellborder="0" cellpadding="6"><tr><td>reads</td></tr></table>>]
  router -> archive [label=<<table border="0" cellborder="0" cellpadding="6"><tr><td>stores</td></tr></table>>]
  router -> inbox [label=<<table border="0" cellborder="0" cellpadding="6"><tr><td>copies</td></tr></table>>]
  inbox -> b [label=<<table border="0" cellborder="0" cellpadding="6"><tr><td>reads</td></tr></table>>]
}

Every message, mine included, takes the same path: its sender’s topic, the router, the recipient’s inbox. The router labels a copy as mine only when it read the original from one of my own topics. The copies are numbered per inbox, so a client notices a missing one and asks the router for it again.

The router is a single point of delivery, and nothing bypasses it. If it stops, messages wait in ntfy. They arrive when it is back, up to a day later, in order within each conversation. A watchdog restarts it when it hangs. I accepted that the router’s correctness now carries my word. If that ever needs more, my page can sign my messages and the clients can check the signature.

Things That Were Not Obvious

  • The MCP protocol version. Claude Code does not register a channel that negotiates the MCP protocol version 2026-07-28, so my server answers with 2025-11-25.
  • A false alarm at start. Claude Code often says that no MCP server with the channel’s name is configured. It checks the name before the server has connected. The channel registers anyway, about two seconds later.
  • ntfy’s bandwidth budget. ntfy charged every poll to a visitor’s daily attachment bandwidth. My whole network segment counted as one visitor. One day, the presence polls used it up. Every session showed as offline, while messages still flowed. I set the limit high enough not to matter.
  • Failed logins lock out an address. ntfy allows a visitor 30 failed logins, then refuses every request with a token from that address. A leftover old token in a loop could have locked out every agent behind the same address.
  • Publishing on a GET. ntfy also accepts a publish through a plain GET. Since my page’s proxy adds my token, a link clicked on another site could have posted as me. nginx now refuses those paths. Every write through the proxy also needs a header that only the page sends.
  • Attachments. A file shown inline on the page’s origin could run a script with my login and post as me. So an HTML file never opens inline, and an SVG opens only under a policy that allows no script. Every file response carries a sandbox policy.
  • Extra tokens. ntfy lets an account mint further tokens of its own, which would survive a rotation of the secret. nginx blocks that API.
  • Message size. ntfy’s message limit is 4 KB. Its documentation warns against raising it. The client cuts a long permission prompt to fit.

Conclusion

The relay is a small set of parts: ntfy as the transport, a channel script in every session, a router with SQLite, a presence service and one page. The hard part was not passing messages. It was making sure that every sender is named truthfully, especially me, and changing the system while it was in use. Now I can follow all the sessions and answer their questions and prompts from a browser. The sessions can also work together without me in between.