Claude Code Channels: Complete Setup Guide (Telegram & Discord)

This guide is for developers who already know what Claude Code Channels is and are ready to set it up. If you need the full explanation first, read the complete Claude Code Channels overview before continuing here.

‍

Key Takeaways

• Bun is required, not Node.js: the plugin silently fails on Node.js with no helpful error message; install Bun first or nothing will work.
• Test with Fakechat before touching Telegram or Discord: ten minutes locally saves hours of debugging external bot configuration.
• Switch to allowlist immediately after pairing: default pairing mode means anyone who messages your bot gets a pairing code reply.
• --channels flag is required every session: being in .mcp.json alone does not activate a channel; you must name it explicitly in the flag.
• Permission prompts stall sessions silently: Claude cannot be unblocked remotely; run inside tmux or screen for sessions you plan to leave unattended.
• Team and Enterprise users: admin must enable Channels in managed settings before any individual setup works; do this first.

‍

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

‍

‍

What Is Claude Code Channels (And Why Should You Care)

A Channel is an MCP server that pushes events into your running Claude Code session. It is two-way: you message it from your phone, Claude does the work and messages back through the same channel.

The core use case is simple. Start a long task, step away from your desk, and receive updates and completions on your phone through Telegram or Discord.

Channels is currently a research preview. The protocol and plugin commands may change before general availability.

‍

Before You Start (Check These First or You Will Hit a Wall)

Skipping this section is why most setup failures happen. Verify all four conditions before installing anything.

• Claude Code v2.1.80 or later: run claude --version in your terminal and update if needed before proceeding with any channel setup.
• Bun runtime specifically: the pre-built channel plugins are Bun scripts and will not run on Node.js or Deno; run bun --version to confirm it is installed; if not, install with curl -fsSL https://bun.sh/install | bash.
• claude.ai login only: API key and Console authentication do not work with Channels; you must be authenticated with a claude.ai account on Pro, Max, Team, or Enterprise.
• Team and Enterprise users: your admin must enable Channels in managed settings before individual setup works at all; go to claude.ai, then Admin settings, then Claude Code, then Channels, and set channelsEnabled to true; do this before any user attempts setup or every step will fail silently.

‍

Test It Locally First With Fakechat (Skip This and You Will Regret It)

Fakechat is an officially supported demo channel that runs a local chat UI at localhost:8787. No Telegram account, no bot token, no Discord server, nothing external to configure.

It is the fastest way to confirm your Claude Code and Bun setup is working correctly before you invest time in external platform setup.

If Fakechat does not work, Telegram and Discord will not work either. Find the problem here where it is cheap to fix.

Install and run:

# Inside an active Claude Code session
/plugin install fakechat@claude-plugins-official

# Exit and relaunch with the channels flag
claude --channels plugin:fakechat@claude-plugins-official

# Open in your browser
http://localhost:8787


What success looks like: type any message in the browser UI, see it arrive in your Claude Code terminal, and receive Claude's response back in the browser. If that loop completes cleanly, your setup is correct and you are ready for external platforms.

‍

Telegram Setup (Step-by-Step)

Step 1: Create Your Bot via BotFather

Open Telegram and start a chat with @BotFather. Send /newbot and follow the prompts. BotFather asks for two things: a display name and a unique username ending in bot.

BotFather replies with a token that looks like 123456789:AAHfiqksKZ8.... Copy it including the leading number and colon. Treat this token like a password. Never commit it to a repository, never paste it in a public chat, never put it in a file that gets shared.

‍

Step 2: Install the Plugin

Inside an active Claude Code session, run:

/plugin install telegram@claude-plugins-official

‍


Step 3: Configure Your Token

/telegram:configure <your_token_here>


This saves the token to .claude/channels/telegram/.env in your project.

‍

Step 4: Exit and Relaunch With the Channels Flag

This step is the most commonly skipped. The session will not activate the channel without a full restart.

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

‍


Step 5: Pair Your Device

Open Telegram, find your bot, and send any message. The bot replies with a six-character pairing code. Back in your Claude Code terminal, run:

/telegram:pair <code>


If your bot does not respond, the session is not running with the --channels flag. Verify and restart.

‍

Step 6: Switch to Allowlist Immediately

In default pairing mode, anyone who messages your bot receives a pairing code reply. Switch to allowlist before you use the channel for anything real.

/telegram:access policy allowlist


Your user ID is added to the allowlist automatically during pairing. Ask Claude to do it, or run the command directly.

‍

Discord Setup (Step-by-Step)

Step 1: Create a Bot in the Discord Developer Portal

Go to discord.com/developers/applications, click New Application, and name it. Navigate to the Bot section, create a username, click Reset Token, and copy the token. Same rule applies: treat it like a password, never commit it anywhere.

‍

Step 2: Enable Message Content Intent (Most Commonly Missed Step)

In your bot's settings, scroll to Privileged Gateway Intents and enable Message Content Intent. This is the step that silently breaks most Discord setups. Without it, your bot connects but receives no message content and appears to do nothing.

‍

Step 3: Set Bot Permissions and Invite to Your Server

Go to OAuth2 > URL Generator. Select the bot scope. Enable the following permissions: Read Messages/View Channels, Send Messages, Read Message History, Add Reactions, Manage Messages.

Copy the generated URL and open it to invite the bot to your server.

‍

Step 4: Install the Plugin and Configure

Inside an active Claude Code session:

/plugin install discord@claude-plugins-official
/discord:configure <your_token_here>

‍


Step 5: Exit and Relaunch With the Channels Flag

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

‍


Step 6: Pair and Lock Down

DM your bot on Discord. It replies with a pairing code. Back in Claude Code:

/discord:pair <code>


Switch from pairing mode to allowlist immediately after pairing, same as with Telegram.

‍

Running Multiple Channels at Once

You can run Telegram and Discord simultaneously in the same session. Space-separate the plugins in the --channels flag.

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


Each channel is independent. Messages from Telegram arrive as Telegram events; messages from Discord arrive as Discord events. Claude can reply to each through the correct channel.

‍

Security (What Most Guides Skip)

• Switch from pairing to allowlist immediately: pairing mode is for first-time setup only; in pairing mode anyone who messages your bot can obtain a pairing code and access your session; switch to allowlist as the first thing you do after confirming the channel works.
• Token security: your bot token is the authentication credential for your Claude Code session; treat it with the same care as an SSH key; if it ends up in a public repository, revoke it in BotFather or the Discord Developer Portal immediately and generate a new one.
• --dangerously-skip-permissions exists and has a specific use case: this flag allows Claude to proceed through permission prompts without local approval, which is necessary for fully unattended sessions; only use it in isolated, trusted environments like a dedicated development VM or container where the consequences of an unexpected file operation are recoverable.
• Being in .mcp.json alone does NOT activate a channel: the MCP server connects and its tools work, but channel messages will not arrive unless the plugin is explicitly named in the --channels flag at session start; this is the most common configuration misunderstanding.

‍

What Actually Happens When You Are Away

This section explains the failure mode that catches most developers the first time they try to use Channels for real unattended work.

‍

Claude pauses silently on permission prompts. If Claude Code encounters a file write, a command execution, or any action requiring approval while you are away from your terminal, the session stops and waits. It does not notify you through Telegram or Discord.

‍

It does not time out. It just sits there until you return to your terminal and approve or deny the action locally.

This is the number one cause of stalled unattended sessions.

• You cannot approve permission prompts remotely: the current research preview has no remote approval mechanism; the only options are approve locally when you return, or use --dangerously-skip-permissions in environments where you accept the risk.
• Events only arrive while the session is open: if Claude Code terminates for any reason, messages sent to your bot while the session was closed are not queued; they are lost and Claude never sees them.
• For reliable unattended use, run inside tmux or screen: these terminal multiplexers keep your session alive through terminal disconnects and SSH drops; start Claude Code inside a tmux session and your channel stays active even if your local terminal closes.

# Start a named tmux session
tmux new -s claude

# Run Claude Code with channels inside it
claude --channels plugin:telegram@claude-plugins-official

# Detach and leave it running
Ctrl+B then D


Reattach later with tmux attach -t claude to check on progress or handle any permission prompts that paused the session.

‍

File and Photo Handling via Telegram

A few Telegram-specific behaviors are worth knowing before you start sending files to your Claude Code session.

• Telegram compresses photos automatically: if you send a photo to your bot, Telegram compresses it before delivery; if you need the original uncompressed file for Claude to process, long-press the image and select Send as File before sending.
• The bot has no message history: Telegram's Bot API does not expose chat history; your bot only sees messages as they arrive after the session starts; messages sent before your Claude Code session was running are not retrievable.
• Max 50MB per file: files above 50MB cannot be sent through the bot; split or compress before sending if your files exceed this limit.
• Shell environment variable takes precedence over .env file: if you are debugging token issues, set TELEGRAM_BOT_TOKEN in your shell environment and it will override whatever is in .claude/channels/telegram/.env; useful for testing a new token without editing files.

‍

Troubleshooting (When Things Do Not Work)

Bot not responding to messages Your Claude Code session is not running with the --channels flag. The bot only responds while the channel is active. Verify the session is running and restart with the flag explicitly included.

Plugin not loading or failing silently Bun is missing or not installed correctly. Run bun --version to confirm. If the command is not found, install Bun with curl -fsSL https://bun.sh/install | bash, then restart your terminal and try again.

Messages not arriving in Claude Code The plugin is in your .mcp.json but not named in --channels. Add it explicitly to the flag. Being configured is not the same as being activated.

Session keeps stalling mid-task Claude hit a permission prompt while you were away. Return to your terminal, check what is waiting for approval, and either approve it locally or rerun the session with --dangerously-skip-permissions if the environment is trusted and isolated.

Team or Enterprise setup failing at every step Your organization admin has not enabled Channels in managed settings. Go to claude.ai, then Admin settings, then Claude Code, then Channels, and enable it. No individual user can work around this organizational setting.

‍

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

‍

‍

Want to Build AI Systems for Your Business?

Claude Code Channels is a powerful tool for individual developer workflows. Building AI-powered systems that operate at team scale, integrate with your existing infrastructure, and run reliably in production requires a different approach.

At LowCode Agency, we are a strategic product team that designs, builds, and evolves custom AI-powered tools, automation systems, and business software for growing SMBs and startups. We are not a dev shop.

• AI strategy before tooling: not sure how Claude Code, Channels, and the broader AI development ecosystem fit into your engineering operations? Our AI consulting service maps your current workflow, identifies where AI creates real leverage, and defines a build plan before any development begins.
• Custom AI agent development: we design and build AI agents tailored to your specific business workflows rather than configuring general platforms that approximate what you need.
• Production-grade reliability: every system we build handles real operational load with proper error handling and output quality your team depends on every day.
• Full product team on every project: strategy, UX, development, and QA working together from discovery through deployment and beyond.
• Long-term partnership after launch: we stay involved after delivery, evolving your AI systems as your operations and requirements grow.

We have shipped 350+ products across 20+ industries. Clients include Medtronic, American Express, Coca-Cola, and Zapier.

If you are serious about building AI-powered systems that work reliably at production scale, let's talk at lowcode.agency/contact.