# Channels: Push External Events into Sessions [Beta]

> **Beta Feature**: Channels is currently in Beta. Features and interfaces may be adjusted based on feedback.

A Channel is an MCP server that pushes messages, alerts, and webhooks into your running CodeBuddy Code session, allowing CodeBuddy Code to react to external events even when you're not at the terminal.

Channels can be two-way: CodeBuddy Code reads events and replies through the same channel, acting like a chat bridge. Events only arrive while a session is open; for continuous operation, run CodeBuddy Code in a background process or persistent terminal.

You can enable channels by installing plugins or using built-in channels. WeChat, Telegram, Discord, and the fakechat demo are all supported.

When CodeBuddy Code replies through a channel, the terminal shows the tool call and confirmation (e.g., "sent"), while the actual reply content appears on the corresponding chat platform.

This page covers:

* [Supported Channels](#supported-channels): WeChat, Telegram, Discord, and fakechat setup
* [Quick Start](#quick-start): Quick hands-on experience with the WeChat channel
* [Security](#security): Sender allowlists and pairing flows
* [Organization Controls](#organization-controls): Enabling channels for teams and enterprises
* [Feature Comparison](#feature-comparison)

To build your own channel, see the [Channels Reference](./channels-reference.md).

## Supported Channels

### WeChat (Built-in)

The WeChat channel is built into CodeBuddy Code and requires no plugin installation. It enables two-way messaging through WeChat ClawBot, supporting text, images, and file exchange.

**Prerequisites**:
- WeChat version iOS 8.0.70 or above
- Enable the ClawBot plugin in WeChat (WeChat > Me > Settings > Plugins > ClawBot)

**QR Code Binding**:

1. In CodeBuddy Code, run `/remote-control wechat` or `/remote-control` and select wechat
2. The terminal displays a QR code (if the QR code doesn't render correctly, a browser link will be provided)
3. Scan the QR code with WeChat and confirm
4. After successful binding, message reception starts automatically

**Usage**:

After binding, send messages in the WeChat ClawBot conversation, and they will automatically appear in the CodeBuddy Code session:

```
#wechat · user_id: Hello, help me look at this bug
```

CodeBuddy Code processes the message and replies via the `WechatReply` tool, with the reply appearing in WeChat.

Supported message types:

| Type | Receive | Send |
|------|---------|------|
| Text | Supported | Supported |
| Image | Supported (auto-downloaded and decrypted locally) | Supported (auto-encrypted and uploaded to CDN) |
| File | Supported | Supported |

**Credential Management**:

After successful QR code scanning, credentials are saved to `~/.codebuddy/channels/wechat/credentials.json`. On next startup, saved credentials are used automatically without re-scanning.

```bash
# Check connection status
/remote-control wechat status

# Disconnect
/remote-control wechat stop

# Reconnect (using saved credentials)
/remote-control wechat start
```

### Telegram

Requires plugin installation. See the full [Telegram plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram).

1. Create a bot via [BotFather](https://t.me/BotFather) in Telegram and obtain a token
2. Install the plugin: `/plugin install telegram@claude-plugins-official`
3. Configure the token: `/telegram:configure <token>`
4. Start: `codebuddy --channels plugin:telegram@claude-plugins-official`
5. Send a message to the bot to get a pairing code, then run `/telegram:access pair <code>` to complete pairing

### Discord

Requires plugin installation. See the full [Discord plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord).

1. Create an application and bot in the [Discord Developer Portal](https://discord.com/developers/applications)
2. Enable Message Content Intent and invite the bot to your server
3. Install the plugin: `/plugin install discord@claude-plugins-official`
4. Configure the token: `/discord:configure <token>`
5. Start: `codebuddy --channels plugin:discord@claude-plugins-official`
6. DM the bot to get a pairing code, then run `/discord:access pair <code>` to complete pairing

### fakechat (Demo)

fakechat is an officially supported demo channel that runs a chat UI on localhost, requiring no authentication or external services.

```bash
# Install
/plugin install fakechat@claude-plugins-official

# Start
codebuddy --channels plugin:fakechat@claude-plugins-official
```

Open `http://localhost:8787` to start chatting.

## Quick Start

Using the WeChat channel as an example, here's a quick walkthrough of the full two-way communication flow:

**Step 1: Ensure ClawBot is Enabled**

In WeChat, go to **Me > Settings > Plugins**, find ClawBot and enable it.

**Step 2: QR Code Binding**

Start CodeBuddy Code and run:

```
/remote-control wechat
```

The terminal displays a QR code. Scan it with WeChat and confirm the binding.

**Step 3: Send a Message**

In the WeChat ClawBot conversation, send:

```
Help me check what files are in the current directory
```

The message arrives in the CodeBuddy Code session, displayed as:

```
#wechat · user_id: Help me check what files are in the current directory
```

CodeBuddy Code executes the task and replies via the `WechatReply` tool, with the reply appearing in WeChat.

**Step 4: Send an Image**

Send a screenshot to ClawBot in WeChat. CodeBuddy Code will automatically download and recognize the image content. You can ask it to edit the image and send it back:

```
Add a hat to the person in the image
```

CodeBuddy Code uses the ImageEdit tool to process the image, then sends the edited image back to WeChat via `WechatReply`.

## Security

### WeChat

The WeChat channel ensures security through ClawBot's QR code authentication mechanism. Only the WeChat account that completed the QR code binding can send messages; messages from others are silently discarded.

Credentials (containing bot_token and account_id) are saved locally with permissions set to 600 (owner read/write only).

### Plugin Channels

Plugin channels like Telegram and Discord maintain a sender allowlist. Trusted senders are added through a pairing flow:

1. Send any message to the bot
2. The bot replies with a pairing code
3. Confirm the pairing code in CodeBuddy Code
4. The sender's ID is added to the allowlist

The allowlist also controls [permission relay](./channels-reference.md#permission-relay). People who reply through a channel can approve or deny tool calls, so only add trusted senders to the allowlist.

### Other Security Considerations

- Configuring in `.mcp.json` alone is not sufficient to push messages; the channel must also be specified in `--channels`
- Organizations can enforce unified controls via the `channelsEnabled` setting

## Organization Controls

Channel functionality is controlled by the `channelsEnabled` setting:

| Plan Type | Default Behavior |
|-----------|-----------------|
| Individual users | Available; users enable per-session via `--channels` |
| Team/Enterprise | Disabled by default; admins must explicitly enable |

### Enabling Channels for Organizations

Admins can set this in `settings.json`:

```json
{
  "channelsEnabled": true
}
```

Once enabled, users in the organization can use `--channels` to connect channel servers to their sessions. If the setting is disabled, MCP servers still connect and tools remain available, but channel messages will not arrive.

## Feature Comparison

CodeBuddy Code has multiple features for connecting to external systems, each suited to different scenarios:

| Feature | Purpose | Use Case |
|---------|---------|----------|
| Standard MCP Server | CodeBuddy Code queries it during tasks; does not push to session | On-demand reading or querying systems |
| Remote Control | Control a local session from remote | Operating an active session when away from your desk |
| **Channel** | **Pushes external events into a running local session** | **Chat bridges, webhook reception, alert response** |

Channels fill the gap by pushing events from non-CodeBuddy Code sources into a running local session:

* **Chat bridge**: Ask CodeBuddy Code questions via WeChat, with answers appearing in WeChat, while the actual work runs on your machine using your real files
* **Webhook receiver**: When webhooks from CI, error trackers, or deployment pipelines arrive, CodeBuddy Code already has your files open and remembers what you were debugging

## Next Steps

* [Build your own Channel](./channels-reference.md): Create a channel for systems that don't have a plugin yet
* Use `/remote-control` to manage all remote control connections
