Guide
A channel server is a small local process that pushes events into your session — it might watch a file or a mailbox, poll on a schedule, or fire on whatever else is worth reacting to. The diagram below follows a single event the whole way: the server pushes it, channels wakes the session, and the agent reads it and can answer through a tool the same server registered. The rest of the page follows that flow — when a push starts a turn and when it waits, and what already speaks the protocol today.
the flow
An event begins in the tool you connected, and the agent decides what to do with it — act on it through a tool the server registered, or simply take it in as context. Anything it sends back goes out through that same server, so the one that raised the event is the one the agent talks to. Watch it play once below, and read the caption as each step lights up.
The diagram shows an event arriving while the session is idle, which is the case that starts a turn on its own. An event that arrives while the agent is mid-turn is held and delivered once the turn settles, so a running turn is never cut off; the next section covers both. The tools a server registers are proxied straight back to it, so the agent answers the event through the process that raised it.
wake semantics
Whether a push starts a turn or joins the next one depends only on what the session is doing when it arrives. The rules are the same for every server, so the guidance a server writes for the agent stays true wherever it runs.
AGENT_SESSION_ID is passed into each server's environment at spawn, retries included, and never written to the host process's environment, so a server can read it at startup and scope itself to the session that spawned it.
what drives a session
A channel server is just a subprocess you chose to run, so the range of things that can reach a session is the range of things on your machine worth reacting to. Three already ship, and the reference server in the docs is the pattern for the rest.
muster, a local multi-agent coordination bus, ships a channel server as muster channel. Mail sent to a session's alias wakes it, and the server's get_thread and reply tools let the agent read the thread and answer without leaving the session.
galley, a browser review surface, ships one as galley channel. A reviewer pressing Revise becomes a push carrying the round's instructions, and the agent edits the document and acknowledges while the reviewer watches the same file.
The reference server watches a file and pushes its contents when the file changes, in about sixty dependency-free lines. The same shape fits a build watcher, an issue tracker, cron output, or a queue consumer: spawn, hand shake, push events, register tools.
Ready to connect one? pi install npm:channels.tools, then point it at a server — the docs walk through the config and the protocol.