117 lines
5.4 KiB
Markdown
117 lines
5.4 KiB
Markdown
---
|
|
title: "Channels — Push Events Into a Running Session"
|
|
aliases: [channels, claude-channels, push-events, mcp-channels]
|
|
tags: [claude-code, channels, mcp, real-time, webhooks, messaging]
|
|
sources: [raw/Push events into a running session with channels.md]
|
|
created: 2026-04-17
|
|
updated: 2026-04-17
|
|
---
|
|
|
|
# Channels — Push Events Into a Running Session
|
|
|
|
Channels are MCP servers that **push events into your running Claude Code session** so Claude can react to external events without polling. Requires Claude Code v2.1.80+, claude.ai login (no Console/API key auth).
|
|
|
|
## What Channels Are
|
|
|
|
- An MCP server that **delivers** messages to your session rather than waiting to be queried
|
|
- **Two-way**: Claude reads the event and replies back through the same channel
|
|
- Events only arrive while the session is open — for always-on use, run Claude in a background/persistent terminal
|
|
- Installed as a **plugin**, configured with your own credentials
|
|
|
|
## Supported Channels
|
|
|
|
All require [Bun](https://bun.sh/) to run:
|
|
|
|
| Channel | Notes |
|
|
|---------|-------|
|
|
| **Telegram** | Official plugin, pairing-code auth |
|
|
| **Discord** | Official plugin, pairing-code auth |
|
|
| **iMessage** | Auth via texting yourself; add contacts with `/imessage:access allow` |
|
|
| **fakechat** | Demo only — localhost UI, no credentials needed |
|
|
|
|
You can also [build a custom channel](https://code.claude.com/docs/en/channels-reference).
|
|
|
|
## How to Enable
|
|
|
|
1. Install the channel as a plugin
|
|
2. Pass `--channels <plugin-name>` when starting Claude Code
|
|
3. Being in `.mcp.json` alone is **not enough** — the server must also be named in `--channels`
|
|
|
|
## Security Model
|
|
|
|
- Each channel maintains a **sender allowlist** — only approved IDs deliver messages
|
|
- **Telegram/Discord**: bootstrap via pairing code exchange; Claude prompts you to approve
|
|
- **iMessage**: texts from yourself auto-approved; others added with `/imessage:access allow`
|
|
- Allowlist also gates **permission relay** — anyone on the list can approve/deny tool use remotely
|
|
- Only allowlist senders you trust with that authority
|
|
|
|
## Permission Handling While Away
|
|
|
|
If Claude hits a permission prompt while you're away:
|
|
- Session **pauses** until you respond
|
|
- Channels that declare the [permission relay capability](https://code.claude.com/docs/en/channels-reference#relay-permission-prompts) can forward prompts to you for remote approval/denial
|
|
- `--dangerously-skip-permissions` bypasses all prompts — use only in trusted environments
|
|
|
|
## Enterprise Controls
|
|
|
|
Channels are **off by default** on Team and Enterprise plans.
|
|
|
|
| Setting | Effect | Default |
|
|
|---------|--------|---------|
|
|
| `channelsEnabled` | Master switch — must be `true` for any channel to work | Channels blocked |
|
|
| `allowedChannelPlugins` | Override Anthropic's default plugin allowlist with your own | Anthropic default list |
|
|
|
|
- Pro/Max individual users skip these checks entirely
|
|
- Admins configure via [claude.ai Admin settings → Claude Code → Channels](https://claude.ai/admin-settings/claude-code)
|
|
- `allowedChannelPlugins` replaces (not extends) the Anthropic list when set
|
|
|
|
```json
|
|
{
|
|
"channelsEnabled": true,
|
|
"allowedChannelPlugins": [
|
|
{ "marketplace": "claude-plugins-official", "plugin": "telegram" },
|
|
{ "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }
|
|
]
|
|
}
|
|
```
|
|
|
|
## Primary Use Cases
|
|
|
|
- **Chat bridge**: ask Claude from your phone via Telegram/Discord/iMessage; answer appears in same chat while work runs locally against your real files
|
|
- **Webhook receiver**: CI results, error tracker alerts, deploy pipeline events arrive where Claude already has your files open and remembers what you were debugging
|
|
|
|
## How Channels Compare to Other Features
|
|
|
|
| Feature | Push vs Pull | Use when |
|
|
|---------|-------------|----------|
|
|
| Channels | **Push into running local session** | React to external events in real time |
|
|
| Standard MCP server | Pull (Claude queries it) | Give Claude on-demand read/query access |
|
|
| [[wiki/claude-code/overview\|Claude Code on the web]] | Async cloud sandbox | Delegate self-contained async work |
|
|
| Remote Control | You drive your local session | Steer in-progress session from phone/web |
|
|
| Scheduled tasks | Timer-based poll | Regular checks, not event-driven |
|
|
|
|
## Research Preview Caveats
|
|
|
|
- `--channels` only accepts plugins from the Anthropic allowlist (or org allowlist)
|
|
- Syntax and protocol contract may change
|
|
- Use `--dangerously-load-development-channels` to test custom channels you're building
|
|
|
|
## Key Takeaways
|
|
|
|
- Channels solve the **push problem**: standard MCP is pull-only, channels deliver events to your session
|
|
- Requires explicit opt-in per session via `--channels` flag
|
|
- Security is enforced by a **sender allowlist** — not just by being in `.mcp.json`
|
|
- Enterprise orgs must enable `channelsEnabled` before any channel delivers messages
|
|
- The allowlist double-gates permission relay — anyone on it can approve tool use remotely, so vet carefully
|
|
- For always-on reactivity, run Claude in a persistent/background terminal session
|
|
|
|
## Related Articles
|
|
|
|
- [[wiki/claude-code/mcp-integration|MCP Integration]] — standard (pull) MCP setup
|
|
- [[wiki/claude-code/overview|Claude Code Overview]] — surfaces, capabilities, CLI flags
|
|
- [[wiki/claude-code/create-plugins|Create Plugins]] — how to build your own channel plugin
|
|
- [[wiki/claude-code/agent-teams|Agent Teams]] — multi-session orchestration
|
|
|
|
---
|
|
|
|
*Source: raw/Push events into a running session with channels.md*
|