# Claude Code Channels — Reference Snapshot

Snapshot of the official Anthropic docs on **Channels**, the MCP-over-stdio push primitive that the agent-watcher MCP Watcher (Layer 2) targets.

Fetched 2026-05-06 from `https://code.claude.com/docs/en/`.

| File | Source | What's in it |
|---|---|---|
| `channels.md` | `/en/channels.md` | Overview: what channels are, supported plugins (Telegram/Discord/iMessage/fakechat), enterprise controls, comparison to other Claude Code surfaces. |
| `channels-reference.md` | `/en/channels-reference.md` | **The implementation reference.** Server options, notification format, full webhook-receiver walkthrough, two-way reply tools, sender gating, permission relay. This is the primary doc for Layer 2. |
| `routines-summary.md` | `/en/routines.md` (summarized) | Brief summary of Routines, the *adjacent* Anthropic managed-cloud cron primitive. We are NOT building on Routines — included for context only. |

## Why this matters for agent-watcher

Layer 2 (MCP Watcher) is implemented as a Channel — an MCP server declared in each agent's `mcp.json`, spawned by Claude Code over stdio. It emits `notifications/claude/channel` events when new pings arrive in the inbox, surfacing them mid-session. See `agent-watcher.md` §4.

Key facts confirmed by the reference docs (relevant to our spec):

- **Capability key:** `experimental: { 'claude/channel': {} }` registers the channel listener.
- **Notification method:** `notifications/claude/channel` with `params.content` (string body) and `params.meta` (string→string map of attributes).
- **Events arrive as:** `<channel source="agent-watcher" ...>BODY</channel>` injected into Claude's context.
- **Reply tools:** standard MCP tools registered via `ListToolsRequestSchema` / `CallToolRequestSchema`. Maps cleanly to our `ack` / `respond` / `mark_handled` plan.
- **Research preview gotcha:** custom channels (anything not on Anthropic's allowlist) require launching with `--dangerously-load-development-channels server:agent-watcher`. We'll document this in INSTALL.md.
- **Lifecycle:** Claude Code spawns the MCP server as a stdio subprocess on session start. Server runs while session is open. No keep-alive responsibility on the server side — stdio close = shutdown.
- **Min version:** Claude Code v2.1.80 (channels) / v2.1.81 (permission relay, which we are NOT using in v1).

## Caveat

This is a snapshot, not a live mirror. If you find behavior that doesn't match these docs, trust live behavior over this snapshot and update via:

```
cd /home/bob/agent-watcher && /home/bob/.local/bin/refresh-channels-docs   # TODO if this becomes painful
```

For now, manual re-fetch when something feels off.