Channels User Guide

Channels User Guide

Push events into a running Claude Code session with channels. Forward CI results, chat messages, monitoring alerts, and webhook events so Claude can react while you're away. Requires Claude Code v2.1.80+. Research preview — requires claude.ai login.

Overview

A channel is an MCP server that pushes events into your running Claude Code session, so Claude can react to things that happen while you're not at the terminal. Channels can be two-way: Claude reads the event and replies back through the same channel, like a chat bridge.

Events only arrive while the session is open. For always-on setups, run Claude in a background process or persistent terminal.

Key Differences from Other Features

Channels fill the gap by pushing events from non-Claude sources into your already-running local session.

Supported Channels

Telegram

1. Create bot: Open BotFather, send /newbot, copy the token
2. Install: /plugin install telegram@claude-plugins-official
3. Configure: /telegram:configure <token> (saves to ~/.claude/channels/telegram/.env)
4. Start: claude --channels plugin:telegram@claude-plugins-official
5. Pair: Message your bot on Telegram, get pairing code, run /telegram:access pair <code>
6. Lock down: /telegram:access policy allowlist

Discord

1. Create bot: Discord Developer Portal → New Application → Bot → Reset Token
2. Enable Message Content Intent: Bot settings → Privileged Gateway Intents → Message Content Intent
3. Invite: OAuth2 → URL Generator → bot scope → View Channels, Send Messages, Send Messages in Threads, Read Message History, Attach Files, Add Reactions
4. Install: /plugin install discord@claude-plugins-official
5. Configure: /discord:configure <token>
6. Start: claude --channels plugin:discord@claude-plugins-official
7. Pair: DM your bot, get code, run /discord:access pair <code>
8. Lock down: /discord:access policy allowlist

iMessage (macOS only)

Reads Messages database directly, sends replies through AppleScript. No bot token needed.

1. Grant Full Disk Access: System Settings → Privacy & Security → Full Disk Access → add your terminal
2. Install: /plugin install imessage@claude-plugins-official
3. Start: claude --channels plugin:imessage@claude-plugins-official
4. Self-chat: Text yourself — bypasses access control automatically
5. Allow others: /imessage:access allow +15551234567 (phone or Apple ID email)

Fakechat (Demo)

Localhost demo channel — no authentication, no external services.

1. Install: /plugin install fakechat@claude-plugins-official
2. Start: claude --channels plugin:fakechat@claude-plugins-official
3. Open UI: http://localhost:8787 and type a message
4. Events arrive as <channel source="fakechat"> tags

Build & Pipeline Use Cases

Channels are especially powerful for CI/CD and infrastructure workflows:

CI/CD Webhook Channel

Push build failures, test results, and deployment status directly into your session:

• Build failure alerts: Claude receives the failure, reads the build log, and starts investigating
• Test result streaming: Failed test details arrive where Claude has your code open
• Deploy status: Post-deploy health checks forwarded for Claude to monitor

Monitoring & Alerting Channel

Forward monitoring events so Claude can react:

• Error tracker webhooks: Sentry/Datadog alerts arrive for immediate root-cause analysis
• Infrastructure alerts: CPU spikes, OOM events, pod restarts
• Log anomalies: Stream unusual log patterns for Claude to investigate

Pipeline Approval Channel

Use the permission relay for remote deployment approvals:

• Claude proposes a deployment action
• Approval prompt forwarded to your phone via Telegram/Discord
• You approve remotely, deployment proceeds

Example: GitHub Actions Webhook → Channel

GitHub Actions → webhook POST to localhost:8788 → Channel Server → Claude Code Session
                                                                    ↓
                                                              Claude reads build log,
                                                              identifies failure,
                                                              proposes fix

Security

Sender Allowlists

Every channel maintains a sender allowlist. Only approved IDs can push messages — everyone else is silently dropped.

Telegram/Discord pairing flow:

1. Send any message to your bot
2. Bot replies with pairing code
3. Approve in Claude Code: /telegram:access pair <code> or /discord:access pair <code>
4. Lock to allowlist: /telegram:access policy allowlist

iMessage: Self-chat bypasses automatically. Add others with /imessage:access allow.

Important Security Notes

• Being in .mcp.json isn't enough — server must also be named in --channels
• Allowlist also gates permission relay — only allowlist senders you trust with tool approval authority
• Gate on message.from.id, not message.chat.id (prevents group chat injection)

Enterprise Controls

On Team and Enterprise plans, channels are off by default.

Enable for organization

Admin console: claude.ai → Admin settings → Claude Code → Channels or set channelsEnabled: true in managed settings.

Restrict plugins

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" },
    { "marketplace": "claude-plugins-official", "plugin": "discord" },
    { "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }
  ]
}

When set, replaces the Anthropic allowlist entirely. Leave unset for default. Empty array blocks all plugins from allowlist (but --dangerously-load-development-channels still works).

Running Channels

# Single channel
claude --channels plugin:telegram@claude-plugins-official

# Multiple channels (space-separated)
claude --channels plugin:telegram@claude-plugins-official plugin:fakechat@claude-plugins-official

# Development channel (custom/local)
claude --dangerously-load-development-channels server:my-webhook

Research Preview Notes

• Rolling out gradually — --channels flag syntax may change
• Only plugins from Anthropic allowlist (or org allowlist) accepted
• Default approved set: claude-plugins-official
• Test custom channels with --dangerously-load-development-channels

See Also

• Channels Reference — Build your own channel (MCP server implementation)
• MCP Documentation — Underlying protocol
• Plugins — Package channels for distribution
• Remote Control — Drive sessions remotely
• Scheduled Tasks — Poll on a timer instead of reacting to pushed events