Claude Code Channels

Claude Code Channels Setup

Claude Code Channels pushes messages from external platforms (Telegram, Discord) into a running Claude Code session via MCP server plugins.

Prerequisites

• Claude Code v2.1.80+
• Bun runtime
• A claude.ai account (not API key mode)

Platform Selection

Ask which platform(s) the user wants, then follow the relevant reference:

• Telegram: See references/telegram.md
• Discord: See references/discord.md

Both can run simultaneously:

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

Universal Workflow

Regardless of platform, setup follows 6 steps:

1. Create bot on the platform's developer portal 2. Install plugin: /plugin install <platform>@claude-plugins-official 3. Configure token: /<platform>:configure <token> 4. Launch session: claude --channels plugin:<platform>@claude-plugins-official 5. Pair account: DM the bot, get a code, run /<platform>:access pair <code> 6. Lock down: /<platform>:access policy allowlist

Troubleshooting

MCP Server Shows "failed" on Startup

Known race condition — server may fail on cold start but reconnect fine.

Fix: Run /mcp, navigate to the failed server, select Reconnect.

Persistent failures — verify the bot token:

# Telegram
TOKEN=$(grep TELEGRAM_BOT_TOKEN ~/.claude/channels/telegram/.env | cut -d= -f2)
curl -s "https://api.telegram.org/bot$TOKEN/getMe"

# Discord
TOKEN=$(grep DISCORD_BOT_TOKEN ~/.claude/channels/discord/.env | cut -d= -f2)
curl -s -H "Authorization: Bot $TOKEN" https://discord.com/api/v10/users/@me

If unauthorized/401, regenerate the token and update ~/.claude/channels/<platform>/.env.

Plugin Not Found

Add the official marketplace first:

/plugin marketplace add anthropics/claude-plugins-official

Bot Not Responding

1. Session must be running with --channels flag 2. /mcp must show the server as "connected" 3. Telegram: verify token with BotFather 4. Discord: enable Message Content Intent in Developer Portal → Bot → Privileged Gateway Intents

Dependency Issues

Pre-install manually:

cd ~/.claude/plugins/cache/claude-plugins-official/<platform>/<version>
bun install --no-summary

Running as Background Service (tmux)

# Start
tmux new-session -d -s claude-<platform> \
  'claude --dangerously-skip-permissions --channels plugin:<platform>@claude-plugins-official'

# Attach / Detach
tmux attach -t claude-<platform>   # Ctrl+b then d to detach

# After startup, if MCP failed: /mcp → select server → Reconnect

Access Control

Both platforms share the same model. Replace <platform> with telegram or discord.

State Files

~/.claude/channels/<platform>/
├── .env          # Bot token (mode 0o600)
├── access.json   # Policy, allowlist, groups, pending
├── approved/     # Approved user ID → chat ID mapping
└── inbox/        # Downloaded attachments

Discord Channel Setup

Step 1: Create a Discord Bot

1. Go to Discord Developer Portal 2. Click New Application, name it 3. Go to Bot in the sidebar, create a username 4. Click Reset Token, copy it (shown only once) 5. Critical: Scroll to Privileged Gateway Intents, enable Message Content Intent — without this, messages arrive with empty content and the bot silently ignores them

Step 2: Invite the Bot to a Server

Go to OAuth2 → URL Generator:

• Select bot scope
• Enable permissions: View Channels, Send Messages, Send Messages in Threads, Read Message History, Attach Files, Add Reactions
• For channel/thread creation, also enable: Manage Channels, Create Public Threads, Create Private Threads, Manage Threads

Generate the URL with the desired permissions. Replace CLIENT_ID with the application ID:

https://discord.com/oauth2/authorize?client_id=CLIENT_ID&permissions=395405544528&scope=bot

The permission value 395405544528 includes all recommended permissions.

Step 3: Install the Plugin

/plugin install discord@claude-plugins-official

If not found:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install discord@claude-plugins-official

Step 4: Configure the Token

/discord:configure <token>

This saves DISCORD_BOT_TOKEN=... to ~/.claude/channels/discord/.env.

Manual alternative:

mkdir -p ~/.claude/channels/discord
printf 'DISCORD_BOT_TOKEN=<token>\n' > ~/.claude/channels/discord/.env
chmod 600 ~/.claude/channels/discord/.env

Step 5: Launch with Channel Flag

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

Important: The Discord MCP server may show as "failed" on initial startup (race condition). After launch, run /mcp, navigate to plugin:discord:discord, and select Reconnect. It connects successfully on retry.

Step 6: Pair Your Account

1. DM the bot on Discord 2. Bot replies with a 6-character pairing code 3. In Claude Code: /discord:access pair <code>

Step 7: Lock Down

/discord:access policy allowlist

Discord-Specific Notes

Verify Token

TOKEN=$(grep DISCORD_BOT_TOKEN ~/.claude/channels/discord/.env | cut -d= -f2)
curl -s -H "Authorization: Bot $TOKEN" https://discord.com/api/v10/users/@me | python3 -m json.tool

Guild Channels

Discord guild channels are opt-in by channel ID (not guild ID). Enable Developer Mode (User Settings → Advanced) to copy IDs via right-click.

/discord:access group add <channel_id>                # Responds to @mentions only
/discord:access group add <channel_id> --no-mention   # Responds to all messages
/discord:access group add <channel_id> --allow id1,id2  # Restrict to specific users
/discord:access group rm <channel_id>                  # Disable

Threads inherit their parent channel's opt-in — no separate entry needed.

Listing Server Channels via API

To programmatically list channels and their IDs:

TOKEN=$(grep DISCORD_BOT_TOKEN ~/.claude/channels/discord/.env | cut -d= -f2)

# List guilds
curl -s -H "Authorization: Bot $TOKEN" https://discord.com/api/v10/users/@me/guilds

# List channels in a guild (type 0 = text, 2 = voice, 4 = category)
curl -s -H "Authorization: Bot $TOKEN" https://discord.com/api/v10/guilds/GUILD_ID/channels

Creating Channels and Threads via API

The bot can create channels and threads if it has Manage Channels permission:

TOKEN=$(grep DISCORD_BOT_TOKEN ~/.claude/channels/discord/.env | cut -d= -f2)

# Create a text channel
curl -s -X POST "https://discord.com/api/v10/guilds/GUILD_ID/channels" \
  -H "Authorization: Bot $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "channel-name", "type": 0, "topic": "Channel description"}'

# Create a thread (type 11 = public thread)
curl -s -X POST "https://discord.com/api/v10/channels/CHANNEL_ID/threads" \
  -H "Authorization: Bot $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "thread-name", "type": 11, "auto_archive_duration": 1440}'

# Send a message in a channel or thread
curl -s -X POST "https://discord.com/api/v10/channels/CHANNEL_OR_THREAD_ID/messages" \
  -H "Authorization: Bot $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello from the bot!"}'

After creating a channel, add it to access.json for the bot to respond there. Threads inherit from their parent channel automatically.

Tools Available

Delivery Settings

/discord:access set ackReaction 🔨           # Seen acknowledgment (empty string disables)
/discord:access set replyToMode first        # Thread first chunk only (first/all/off)
/discord:access set textChunkLimit 2000      # Discord hard limit is 2000
/discord:access set chunkMode newline        # Split at paragraph boundaries
/discord:access set mentionPatterns '["^hey claude\\b"]'

Multiple Bot Instances

To run multiple bots with different tokens and separate allowlists, set DISCORD_STATE_DIR to a different directory per instance:

DISCORD_STATE_DIR=~/.claude/channels/discord-bot2 claude --channels plugin:discord@claude-plugins-official

Recommended Discord Permission Value

395405544528 includes:

• View Channels, Send Messages, Embed Links, Read Message History
• Attach Files, Add Reactions, Send Messages in Threads
• Create Public/Private Threads, Manage Threads, Manage Channels

Telegram Channel Setup

Step 1: Create a Telegram Bot

1. Open Telegram, search for @BotFather 2. Send /newbot 3. Choose a display name and username (must end in bot) 4. BotFather replies with a bot token like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 5. Copy the token

Step 2: Install the Plugin

/plugin install telegram@claude-plugins-official

If not found:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install telegram@claude-plugins-official

Step 3: Configure the Token

/telegram:configure <token>

This saves TELEGRAM_BOT_TOKEN=... to ~/.claude/channels/telegram/.env.

Manual alternative:

mkdir -p ~/.claude/channels/telegram
printf 'TELEGRAM_BOT_TOKEN=<token>\n' > ~/.claude/channels/telegram/.env
chmod 600 ~/.claude/channels/telegram/.env

Step 4: Launch with Channel Flag

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

Step 5: Pair Your Account

1. Open Telegram and DM the bot 2. Bot replies with a 6-character pairing code 3. In Claude Code: /telegram:access pair <code>

Step 6: Lock Down

/telegram:access policy allowlist

Telegram-Specific Notes

Verify Token

TOKEN=$(grep TELEGRAM_BOT_TOKEN ~/.claude/channels/telegram/.env | cut -d= -f2)
curl -s "https://api.telegram.org/bot$TOKEN/getMe" | python3 -m json.tool

Group Chats

Enable a group by chat ID (negative number for groups):

/telegram:access group add -1001654782309
/telegram:access group add -1001654782309 --no-mention

Tools Available

Delivery Settings

/telegram:access set ackReaction 👀          # Seen acknowledgment
/telegram:access set replyToMode first       # Thread first chunk only
/telegram:access set textChunkLimit 4096     # Max chars per message
/telegram:access set chunkMode newline       # Split at paragraph boundaries
/telegram:access set mentionPatterns '["^hey claude\\b"]'

Limitations

• Telegram Bot API has no message history or search
• Photos are auto-downloaded to ~/.claude/channels/telegram/inbox/
• Bot can only see messages in groups where it's a member and has message access