# channels

> channels makes a running coding-agent session reachable by the other tools
> on your machine. You connect channel servers — small local processes that
> push events into a live pi session — and a push wakes the session when it is
> idle and queues, coalesced, when it is mid-turn. Each server registers its
> own tools with the agent, so the guidance a server sends arrives with the
> tools the agent needs to act on the event. The servers are subprocesses the
> session spawns from your config, and everything runs on your own machine. It
> ships as the npm package channels.tools, a pi extension.

Site: https://channels.tools
Install: pi install npm:channels.tools
Guide: https://channels.tools/guide/  (one event end to end, wake semantics, what drives a session)
Docs: https://channels.tools/docs/  (install, configure, the stdio protocol, a reference server)
Source: https://github.com/schuettc/pi-extensions (packages/channels.tools)
License: MIT
Contact: court@subaud.io
Sister tools: https://muster.tools (local coordination bus), https://galley.tools (document review)

## What it is

A coding-agent session runs in your terminal and acts when you prompt it.
Channels lets the programs around it reach that session directly. Everything
outside the terminal — mail from another agent's session, a review round
landing, a build finishing, a file changing — normally waits for you to relay
it in by hand; channels replaces that relay with a subprocess for each source
of events. The session subscribes through its config, the servers push, and
the agent handles what arrives.

## Wake semantics

- Idle: an event arriving while the session is idle starts a turn immediately,
  delivered with the server's payload and the guidance it wrote for handling it.
- Mid-turn: events arriving while the agent is working are buffered and
  delivered coalesced once the turn settles, so a running turn is never
  interrupted.
- Tools: each server's tools are registered under their own names and proxied
  back to that server, so an instruction a server hands the agent stays true.
- Identity: 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.
- Failure: a server that crashes is retried with backoff and its tools
  re-register on reconnect; a process that does not speak the protocol is
  killed and logged.

## Configure

Channels reads ~/.pi/agent/channels.json (global, every session) and
<project>/.pi/channels.json (project-scoped; a project entry wins over a global
one on a name collision). Nothing connects until one of these files exists.
Each entry under channelServers is a {command, args, env, cwd} the session
spawns as a subprocess, so no server is special-cased.

    { "channelServers": {
        "muster": { "command": "muster", "args": ["channel"] },
        "file":   { "command": "node",   "args": ["examples/file-channel.js", "inbox.txt"] }
    } }

## The protocol

A channel server speaks newline-delimited JSON-RPC 2.0 over stdio: one JSON
object per line on stdin and stdout, with no Content-Length framing. It runs
locally and talks only to the session that spawned it.

1. Handshake — the client sends initialize; the server's result must declare
   capabilities.experimental["claude/channel"], and may include an instructions
   string (injected as guidance) and the tools it exposes. A server that does
   not declare the capability is rejected.
2. Events — the server pushes notifications/claude/channel with freeform text
   and optional meta attributes (count, thread_id, from, ...). The client may
   coalesce pushes; a server that pre-coalesces reports how many events one
   push stands for in meta.count.
3. Tools — a server may expose tools (name, description, JSON-schema input).
   The client registers them under their own names and proxies invocations back
   to the server via tools/call.
4. Shutdown — SIGTERM when the session ends, SIGKILL after a grace period.

## What drives a session

Known channel servers:
- muster (muster channel) — a local multi-agent coordination bus. Mail to a
  session's alias wakes it; get_thread and reply let the agent read and answer.
- galley (galley channel) — a browser document-review surface. A reviewer
  pressing Revise becomes a push carrying the round's instructions.

The reference server, examples/file-channel.js in the package, implements the
whole convention dependency-free (about sixty lines): it watches a file and
pushes its contents when the file changes. `node examples/file-channel.js
--demo` prints the exchange without an agent, and `--demo --wire` prints it as
raw wire frames.