3eda72df28
Snapshot of official Anthropic Channels docs (channels.md, channels-reference.md, routines summary) fetched 2026-05-06 from code.claude.com. Bob needs these to implement the MCP Watcher in Layer 2; the channels-reference.md is the primary implementation reference. docs/channels/README.md cross-references the snapshot back to spec §4 and notes the key facts confirmed: capability key, notification method, lifecycle, the research-preview --dangerously-load-development-channels caveat, and version minimums (v2.1.80 for channels, v2.1.81 for permission relay which we are not using in v1). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
35 lines
2.6 KiB
Markdown
35 lines
2.6 KiB
Markdown
# 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.
|