Claude Code Channel System Documentation

Complete technical analysis of remote Agent control via IM platforms

---

Documentation

01-channel-system.md — Channel System Architecture

A deep dive into the design and implementation of Claude Code's Channel system from a source code perspective, covering:

• What is a Channel: Core concepts of IM integration, MCP protocol foundations
• Architecture Overview: End-to-end message flow, component relationships
• Message Protocol: Inbound notifications, XML wrapping, outbound tool calls
• Six-Layer Access Control: Capability → Runtime gate → OAuth → Org policy → Session allowlist → Plugin approval
• Permission Relay System: Remote tool execution approval, 5-letter request IDs, multi-source racing
• Plugin Architecture: Channel manifest declarations, user config flow, scoped naming
• UI Components: Terminal message rendering, status notices, developer warning dialogs
• Security Design: XML injection prevention, marketplace verification, trust boundary analysis

Target audience: Developers, architects, and plugin authors interested in AI Agent IM integration architecture

---

Illustrations

All illustrations use dark background (#1a1a2e) with Anthropic brand copper-orange (#D97757) accent color.

Image	Description	Document
01-channel-overview.png	Channel system architecture overview	Architecture
02-message-flow.png	End-to-end message flow: IM → Agent → IM	Architecture
03-access-control.png	Six-layer access control gates	Architecture
04-permission-relay.png	Permission relay system flow	Architecture

---

Quick Start

Users

1. Read the Channel System Architecture
2. Learn how to start IM integration with --channels
3. Understand how different platforms (Telegram, Feishu, Discord) connect

Plugin Developers

1. Read the Plugin Architecture section
2. Understand the plugin.json Channel declaration format
3. Implement the MCP Server notifications/claude/channel protocol
4. Key source files:
   • src/services/mcp/channelNotification.ts — Core gating and message wrapping
   • src/services/mcp/channelPermissions.ts — Permission relay system
   • src/services/mcp/channelAllowlist.ts — Allowlist management
   • src/utils/plugins/mcpPluginIntegration.ts — Plugin MCP integration
   • src/utils/plugins/schemas.ts — Plugin manifest Channel schema

---

Core Concepts Reference

Concept	Description
Channel	An MCP Server declaring claude/channel capability that can push IM messages to the Agent
Channel Entry	Parsed --channels argument entry, either plugin or server kind
Channel Gate	Six-layer access control gate deciding whether to register notification handlers
Permission Relay	Mechanism for forwarding tool execution approval prompts to IM platforms
Channel Plugin	A plugin declaring channels field in its plugin.json
Scoped Name	Plugin server name with scope prefix: plugin:{pluginName}:{serverName}
Short Request ID	5-letter permission request identifier generated via FNV-1a hash
Channel Tag	<channel> XML tag wrapping IM message content and metadata
Dev Channels	Channels loaded via --dangerously-load-development-channels for local development
tengu_harbor	GrowthBook runtime feature flag controlling the Channel system master switch

---

Related Resources

• Claude Code Haha Home
• Agent Framework Deep Dive
• Skills System Documentation
• GitHub Issues