foreman/agent-watcher
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
agent-watcher/docs/channels
History
bob-boat 3eda72df28 Add Channels reference docs snapshot for Layer 2 implementation 
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>
2026-05-06 16:04:32 -04:00
..
channels-reference.md Add Channels reference docs snapshot for Layer 2 implementation 2026-05-06 16:04:32 -04:00
channels.md Add Channels reference docs snapshot for Layer 2 implementation 2026-05-06 16:04:32 -04:00
README.md Add Channels reference docs snapshot for Layer 2 implementation 2026-05-06 16:04:32 -04:00
routines-summary.md Add Channels reference docs snapshot for Layer 2 implementation 2026-05-06 16:04:32 -04:00

README.md

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.