Claude Code Channels

1. What Is a Channel?

A Channel connects an external event source to a running local Claude Code session. The external system sends an event through an MCP server, and that event is injected into the session Claude is already using.

The key difference

A normal MCP server is something Claude queries during a task. A Channel can push an event into Claude's running session even when you are not at the terminal.

2. Why Use Channels?

3. Channel Architecture

A Channel is implemented as an MCP server. The channel server receives external messages and injects them into Claude Code as channel events.

Telegram / Discord / iMessage / CI / Webhook
                    │
                    ▼
             Channel MCP Server
                    │
                    ▼
        Running Claude Code Session
                    │
                    ▼
              Claude's tools
                    │
                    ▼
          Reply through the channel

Important: the session must be running

Channel events only arrive while the Claude Code session is open. If you want an always-on setup, run Claude in a background process or another persistent terminal environment.

4. Channels vs Other Claude Code Features

Feature	What it does	Best use
Claude Code on the web	Runs work in a fresh cloud sandbox cloned from GitHub.	Delegate self-contained async work.
Claude in Slack	An @Claude mention starts a web session.	Start work directly from team conversations.
Standard MCP server	Claude queries external tools/data during a task.	On-demand access to systems.
Remote Control	You drive your local session from claude.ai or the mobile app.	Steer an existing session remotely.
Channels	External systems push events into the already-running local session.	Chat bridges, webhooks, CI and monitoring events.

5. Supported Channels

The current research preview includes official plugins for:

Each supported channel is installed as a plugin and requires Bun. The official fakechat channel is also available as a local demonstration.

6. Telegram Channel Setup

Step 1 — Create a Telegram bot

Open Telegram's BotFather and send:

/newbot

Give the bot a display name and unique username ending in bot. Copy the token returned by BotFather.

Step 2 — Install the official plugin

/plugin install telegram@claude-plugins-official

If the official marketplace is unavailable:

/plugin marketplace add anthropics/claude-plugins-official

Then install again.

Step 3 — Configure the token

/telegram:configure <token>

The plugin saves the token under:

~/.claude/channels/telegram/.env

Alternatively, set:

TELEGRAM_BOT_TOKEN

in your shell environment before launching Claude Code.

Step 4 — Start Claude with the channel

Exit Claude Code and restart:

claude --channels plugin:telegram@claude-plugins-official

Step 5 — Pair your account

Send any message to your Telegram bot. The bot returns a pairing code. In Claude Code:

/telegram:access pair <code>

Then restrict access:

/telegram:access policy allowlist

7. Discord Channel Setup

Step 1 — Create a Discord application/bot

Open the Discord Developer Portal, create a new application, go to the Bot section, create a username, reset the token and copy it.

Step 2 — Enable Message Content Intent

In the bot settings, under Privileged Gateway Intents, enable:

Message Content Intent

Step 3 — Invite the bot

Use OAuth2 → URL Generator and select the bot scope with these permissions:

• View Channels
• Send Messages
• Send Messages in Threads
• Read Message History
• Attach Files
• Add Reactions

Step 4 — Install the plugin

/plugin install discord@claude-plugins-official

Step 5 — Configure the bot token

/discord:configure <token>

The plugin stores it under:

~/.claude/channels/discord/.env

You can alternatively set:

DISCORD_BOT_TOKEN

Step 6 — Start Claude with Discord

claude --channels plugin:discord@claude-plugins-official

Step 7 — Pair

DM your Discord bot. It responds with a pairing code:

/discord:access pair <code>

Then restrict access:

/discord:access policy allowlist

8. iMessage Channel Setup

Step 1 — Grant Full Disk Access

The Messages database is:

~/Library/Messages/chat.db

macOS protects this file. When the channel first reads it, allow the access request. If the prompt does not appear, go to:

System Settings → Privacy & Security → Full Disk Access

Add your terminal application. Without this access, the server exits with authorization denied.

Step 2 — Install

/plugin install imessage@claude-plugins-official

Step 3 — Start with Channels

claude --channels plugin:imessage@claude-plugins-official

Step 4 — Text yourself

Open Messages on a device signed into your Apple ID and send a message to yourself. Self-chat bypasses access control without additional pairing.

Step 5 — Allow other senders

/imessage:access allow +15551234567

Handles can be phone numbers in +country format or Apple ID email addresses.

9. Fakechat — Learn Channels Without a Real Platform

Fakechat is the easiest way to understand the Channel architecture. It provides a local chat UI without authentication or an external messaging service.

Requirements

• Claude Code installed and authenticated with claude.ai or a Claude Console API key.
• Bun installed.
• Team/Enterprise/managed Console organizations need Channels enabled by an admin.

Step 1 — Install

/plugin install fakechat@claude-plugins-official

Step 2 — Restart with the channel

claude --channels plugin:fakechat@claude-plugins-official

You can pass multiple channel plugins separated by spaces.

claude --channels plugin:fakechat@claude-plugins-official plugin:telegram@claude-plugins-official

Step 3 — Open the chat UI

http://localhost:8787

Type:

what's in my working directory?

The message enters the running Claude Code session as a channel event. Claude can then call its normal tools and use the channel's reply tool to send the answer back to the browser.

What the terminal sees

← fakechat · web: what's in my working directory?

The model receives a channel event with a scoped source such as:

<channel source="plugin:fakechat:fakechat">

10. Security — Sender Allowlists

Every approved Channel plugin maintains a sender allowlist. Only senders you explicitly add can push messages into the session. Other senders are silently dropped.

Telegram / Discord pairing

1. Send a message to the bot.
2. The bot returns a pairing code.
3. Approve the code in Claude Code.
4. Your sender ID is added to the allowlist.

iMessage

Texting yourself automatically passes the access gate. Other contacts must be added with /imessage:access allow.

11. Permission Relay and Remote Approval

Some channel servers can declare a permission relay capability. This allows permission prompts from Claude Code to be forwarded through the channel.

This is useful when you are away from the terminal, but it increases the importance of sender access control.

Unattended mode

For unattended use, the documentation mentions:

--dangerously-skip-permissions

In non-interactive -p mode, tools that require terminal input, such as multiple-choice questions and plan-mode approval, are disabled so the session does not stall waiting for input.

12. Team and Enterprise Administration

Organizations have controls over whether Channels can be used.

Setting	Purpose
channelsEnabled	Master switch. Must be true for channel messages to be delivered.
allowedChannelPlugins	Controls which channel plugins may register.

Default behavior

Organization/authentication	Default
claude.ai Team / Enterprise	Channels are blocked until an Owner enables them.
Anthropic Console API key	Channels are allowed by default unless managed settings are deployed.
Pro / Max without organization	Organization checks are skipped; user opts in per session with --channels.

Enable Channels

An Owner can enable Channels from the Claude.ai administration area:

Admin settings → Claude Code → Channels

Or managed settings can contain:

{
  "channelsEnabled": true
}

Restrict allowed plugins

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

This lets an organization allow specific official plugins and/or internal plugins.

13. Build Your Own Channel

If the system you care about does not have an official Channel plugin, you can build your own. The documentation provides a Channels reference for this purpose.

Conceptually, your custom Channel needs to:

1. Act as an MCP server.
2. Receive events from your external system.
3. Expose those events to Claude Code as channel events.
4. Optionally expose a reply tool so Claude can respond through the same system.
5. Implement appropriate access control.
6. Package/install it as a plugin.

Example architecture — CI alerts

GitHub Actions / Jenkins / GitLab CI
              │
              ▼
       Your channel server
              │
              ▼
       Running Claude Code
              │
              ▼
       Claude investigates
              │
              ▼
       Reply / status update

Example event

{
  "source": "ci",
  "event": "build_failed",
  "repository": "acme/payments",
  "branch": "main",
  "job": "integration-tests",
  "url": "https://ci.example.com/job/123",
  "message": "17 integration tests failed"
}

Claude can receive the event and use the local repository and normal Claude Code tools to investigate.

14. Testing a Custom Channel During Preview

During the research preview, the normal --channels flag only accepts channel plugins from the effective approved allowlist.

For a channel you are building, the documentation provides:

--dangerously-load-development-channels

15. Research Preview Limitations

Limitation	Meaning
Research preview	The feature is still evolving.
Flag may change	--channels syntax and protocol contract may change.
Not in help	During preview, the flags may work without appearing in claude --help.
Anthropic auth	Requires claude.ai authentication or Console API key.
Provider limitation	Not available on Bedrock, Google Cloud Agent Platform or Microsoft Foundry.
Session must run	Events arrive only while the Claude Code session is open.
Allowlist	Only approved/allowed channel plugins can register during the preview.

16. Real-World Workflow Examples

Example A — CI Failure → Claude

A deployment fails in CI. Instead of manually opening the terminal and explaining the failure, the CI system pushes an event into your running Claude session.

Example B — Spring Boot Monitoring

Imagine a monitoring service reports:

HTTP 500 spike
service=payments
error=DataIntegrityViolationException
rate=18% in 5 minutes

A Channel can deliver that event into the running Claude Code session. Claude can inspect the Spring Boot code, search logs/files and prepare a diagnosis.

Example C — Next.js Production Alert

Vercel deployment failed
branch=main
error=TypeScript compilation failed
file=src/app/dashboard/page.tsx

Claude receives the event, examines the repository and can investigate the relevant TypeScript file.

Example D — Phone-to-Local-Claude

You are away from your laptop but want to ask Claude about the project:

Telegram:
"Check why the integration tests were failing earlier."

Claude receives the message in the existing local session, where it can use the real working directory.

17. Recommended Channel Workflow

1. Decide whether you need push events or simple MCP queries.
2. Choose Telegram, Discord, iMessage, fakechat or a custom Channel.
3. Install the plugin.
4. Configure credentials or access.
5. Start Claude Code with the channel explicitly enabled.
6. Pair your sender where required.
7. Restrict access with an allowlist.
8. Test a harmless message first.
9. Only then connect CI, monitoring or production events.

18. Common Mistakes

Mistake	Why it happens	Fix
Installing plugin but not using --channels	Plugin is installed but not opted into the session.	Restart Claude with --channels plugin:....
Bot does not respond	Claude was started without the channel flag.	Restart with the channel enabled.
Everyone can message the bot	Access control was not configured.	Pair and use an allowlist.
Assuming channel works after Claude exits	Channels deliver to a running session.	Use a persistent/background process for always-on behavior.
Using a local MCP server as a Channel automatically	MCP configuration alone does not enable push delivery.	The server must be named in --channels.
Admin enabled plugin but messages do not arrive	channelsEnabled may be off.	Have an Owner/admin enable Channels.
Custom channel won't register	It is not on the effective preview allowlist.	Use the development flag for testing or configure an org allowlist.
Giving permission relay to untrusted users	Channel sender can approve/deny tool use.	Allowlist only trusted senders.

19. Channel vs Hook vs Scheduled Task

Feature	Trigger	Example
Hook	Claude Code lifecycle event	After Edit → run formatter.
Scheduled task	Time-based schedule	Every morning → run a prompt.
Channel	External pushed event	CI failure → tell running Claude.

20. Quick Cheat Sheet

Goal	Command / setting
Install Telegram	/plugin install telegram@claude-plugins-official
Configure Telegram	/telegram:configure <token>
Pair Telegram	/telegram:access pair <code>
Telegram allowlist	/telegram:access policy allowlist
Start Telegram	claude --channels plugin:telegram@claude-plugins-official
Install Discord	/plugin install discord@claude-plugins-official
Configure Discord	/discord:configure <token>
Pair Discord	/discord:access pair <code>
Discord allowlist	/discord:access policy allowlist
Start Discord	claude --channels plugin:discord@claude-plugins-official
Install iMessage	/plugin install imessage@claude-plugins-official
Start iMessage	claude --channels plugin:imessage@claude-plugins-official
Allow iMessage sender	/imessage:access allow +country-number
Install fakechat	/plugin install fakechat@claude-plugins-official
Start fakechat	claude --channels plugin:fakechat@claude-plugins-official
Fakechat UI	http://localhost:8787
Enable org-wide	"channelsEnabled": true
Restrict plugins	allowedChannelPlugins
Custom channel testing	--dangerously-load-development-channels

21. Interview / Revision Questions

1. What is a Claude Code Channel?
2. How is a Channel different from a normal MCP server?
3. Why must a Claude Code session be running?
4. What external platforms are currently supported in the research preview?
5. Why does every Channel plugin require Bun?
6. How do you start Claude Code with a Channel?
7. What does the --channels flag do?
8. How does Telegram pairing work?
9. How does Discord pairing work?
10. Why does iMessage require macOS Full Disk Access?
11. What is fakechat?
12. Why are sender allowlists important?
13. What is permission relay?
14. Why is permission relay a security concern?
15. What does channelsEnabled control?
16. What does allowedChannelPlugins control?
17. How do Channels differ from scheduled tasks?
18. How would you connect CI failures to a local Claude session?
19. How would you build a custom Channel?
20. Why are Channels still considered research preview?

22. Practice Exercises

23. Final Memory Map

24. Final Takeaway

Channels are useful when Claude needs to react to something that happens outside the terminal. Instead of polling or starting a new cloud session, a Channel can deliver the event directly into the Claude Code process that is already running against your local project.

The strongest mental model is:

Normal MCP:
Claude → asks system → gets data

Channel:
External system → pushes event → Claude's running session → reacts

Hook:
Claude Code event → hook → automation

Scheduled task:
Clock → prompt → Claude

For practical learning, start with fakechat, then try Telegram or Discord, and only after that connect real CI/monitoring systems. Always keep sender access restricted, especially when permission relay or unattended operation is involved.