---
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*