foreman/agent-watcher
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Add Channels reference docs snapshot for Layer 2 implementation

Browse source 
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>
This commit is contained in:
bob-boat 2026-05-06 16:04:32 -04:00
parent c91f76039d
commit 3eda72df28
4 changed files with 1164 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/channels/README.md Normal file
View file

@ -0,0 +1,35 @@
# 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.