Tutorial
Complete Guide to Connecting Claude Code with Telegram
Build Your AI Assistant from Scratch — Including All the Pitfalls and Solutions
2026-05-05 · littlex.org
中文 | 日本語
0. Introduction: Why Connect Claude Code + Telegram
Imagine this: You're on the subway commuting to work, you pull out your phone, open Telegram, and talk to Claude directly using voice messages. It can help you write code, analyze documents, plan your schedule, and even research topics for you. No need to open a laptop, no browser required — your AI assistant lives inside the messaging app you use every day.
Claude Code is a powerful CLI tool on its own, but its Telegram plugin transforms it from "only usable sitting at a computer" to "available anytime, anywhere." This tutorial will walk you through the entire setup from scratch, including all the pitfalls I personally encountered.
Once connected, you can:
- Chat with Claude anytime from your phone (text + voice)
- @mention the bot in group chats to have it join discussions
- Send files for it to analyze
- Use it as a 24/7 always-on personal AI assistant
1. Prerequisites
Before you begin, make sure you have the following:
A Host Machine
Linux or Mac (or a cloud VM). Must be running 24/7 to continuously receive Telegram messages.
Claude Account (choose one)
Option 1: Subscription login — Log in with your paid claude.ai subscription account, fixed monthly fee, suitable for general use.
Option 2: API Key — Apply at
console.anthropic.com, pay-per-use, suitable for heavy use or automation scenarios.
Telegram Account
You need to be able to create a Bot. Any Telegram account will do.
Basic Terminal Skills
Know how to SSH, run commands, and edit config files.
Tip: Recommended Host Options
If you don't have a machine running 24/7, consider a cheap VPS (e.g., Linode's $5/month plan), or a Mac mini / Raspberry Pi sitting at home. The key is that it needs to run continuously.
2. Step 1: Install Bun
Bun is a high-performance JavaScript runtime that the Claude Code Telegram plugin depends on. You must install Bun first before the Telegram plugin will work.
Installation Command (Mac / Linux)
curl -fsSL https://bun.sh/install | bash
After installation, reload your shell configuration:
source ~/.zshrc
source ~/.bashrc
Verify Installation
bun --version
Pitfall: Bun Must Be Pre-installed
The Claude Code Telegram plugin calls Bun to execute its scripts at startup. If Bun is not installed on the system, the plugin will fail silently — no error messages, it just won't respond. This is one of the most common reasons for "the bot isn't responding."
Pitfall (Mac): Don't Install as Root
On Mac, never use sudo to run the install command. Bun's install script places the binary in ~/.bun/bin/. If you run it as root, the path will point to root's home directory, and your regular user won't be able to find bun.
Pitfall (Mac): System Permission Prompts
During installation, macOS may show security permission dialog boxes (e.g., "Allow Terminal to access Downloads"). You must click "Allow", otherwise the installation will fail without showing a clear error message.
Tip: Verify PATH Configuration
If bun --version shows "command not found" after installation, check that your shell config file (~/.zshrc or ~/.bashrc) contains this line:
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
3. Step 2: Install Claude Code
Install Claude Code CLI
npm install -g @anthropic-ai/claude-code
Pitfall (Mac): Don't Install with sudo
Same as Bun, do not use sudo npm install -g. If you encounter permission issues, the correct approach is to change npm's global install path:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
source ~/.zshrc
npm install -g @anthropic-ai/claude-code
Set Up Authentication (Choose One)
Option 1: Log In with Subscription Account (Recommended for Beginners)
If you have a Claude Pro / Team / Max subscription, you can log in directly with your account — no API Key needed:
claude
Subscription Account vs API Key — How to Choose?
Subscription account: Fixed monthly fee (Pro $20/month), suitable for general use, no need to worry about usage.
API Key: Pay-per-use, suitable for heavy automation, precise cost control, or enterprise deployments.
Recommendation: Start with a subscription account, then evaluate whether to switch to API once your usage stabilizes.
Option 2: Use an API Key
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxx"
To make it persist across reboots, add it to your shell config file:
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"' >> ~/.zshrc
source ~/.zshrc
Security Reminder
Your API Key is essentially your credit card. Don't put it in a public git repo or share it with others. If you're using a cloud host, make sure ~/.zshrc has file permissions set to 600 (owner read/write only).
Verify Installation
claude --version
claude -p "say hello"
4. Step 3: Create a Telegram Bot
Create a Bot in Telegram and obtain the Bot Token.
4.1 Create the Bot
- Search for @BotFather in Telegram
- Open the conversation and type
/newbot
- BotFather will ask for the bot's display name (can be anything, e.g., "My AI Assistant")
- Then it asks for a username (must be in English, ending with
_bot, e.g., my_ai_bot)
- Once complete, BotFather will give you a Bot Token in this format:
7123456789:AAF1x2y3z4a5b6c7d8e9f0-AbCdEfGhIjKlM
Tip: Keep Your Bot Token Safe
The Bot Token is like your bot's password. Anyone with the token can control your bot. Store it securely and never share it publicly.
4.2 Configure Group Privacy (Important!)
This is the most commonly overlooked setting. By default, a Bot in a group can only receive the following messages:
- Commands starting with
/
- Messages that @mention the bot
- Replies to the bot's previous messages
If you want the bot to receive all messages in a group (so users don't have to @mention it every time), you need to disable Group Privacy:
- Chat with @BotFather
- Type
/setprivacy
- Select your bot
- Choose Disable
You: /setprivacy
BotFather: Choose a bot to change group messages settings.
You: @your_bot_username
BotFather: 'Disable' - your bot will receive all messages in groups.
'Enable' - your bot will only receive messages that...
You: Disable
BotFather: Success! The new status is: DISABLED.
Pitfall: Group Privacy Must Be Set BEFORE Adding to Group
If your bot is already in a group, after changing the privacy setting, you need to remove the bot from the group and re-add it for the new setting to take effect. This is a known behavior of the Telegram Bot API.
4.3 Get Your Chat ID
The Claude Code Telegram plugin needs to know which chat_ids are allowed to interact (a security measure to prevent strangers from using your bot and consuming your API quota).
How to get your personal Chat ID:
curl -s "https://api.telegram.org/botYOUR_TOKEN/getUpdates" | python3 -m json.tool
Tip: Group Chat IDs
Group chat_ids are negative numbers (e.g., -1001234567890). Use the same getUpdates method — send a message in the group after adding the bot to see it.
5. Step 4: Configure the Claude Code Telegram Plugin
5.1 Set the Bot Token
In the Claude Code CLI, use the configuration command to set up the Telegram plugin:
claude
/telegram:configure
Follow the prompts to paste your Bot Token.
5.2 Set Allowed Chat IDs
For security, you need to configure which chat_ids are allowed to interact with the bot:
/telegram:access
Once configured, the bot will only respond to messages from chat_ids on the allowlist.
5.3 Start Claude Code in Daemon Mode
To keep the bot running continuously, start Claude Code in daemon mode:
claude --daemon
nohup claude --daemon &> ~/claude-daemon.log &
tail -f ~/claude-daemon.log
5.4 Verify
Send a message to your bot in Telegram (e.g., "hello"). If everything is configured correctly, the bot should reply within a few seconds.
Success Indicators
If the bot replies to your message, congratulations! The basic connection is complete. You can now proceed to advanced configuration.
If the Bot Doesn't Respond
Most common reasons (check in this order):
1. Bun not installed — run bun --version to verify
2. Bot Token is wrong — double-check it
3. Chat ID not in allowlist — check access settings
4. Claude Code not running in daemon mode — check the process
6. Step 5: Advanced Configuration
6.1 Voice Message Auto-Transcription (Whisper)
If you want to talk to the bot using voice, you'll need to set up speech-to-text. The Claude Code Telegram plugin supports receiving voice messages and automatically transcribes them using the Whisper model before processing.
pip install faster-whisper
export OPENAI_API_KEY="sk-..."
Tip: Local Whisper vs. API
If your host has a GPU, local Whisper is cheaper and faster. Without a GPU, OpenAI's Whisper API is more practical — about $0.006 per minute of audio.
6.2 Group Support
To use the bot in groups:
- Confirm Group Privacy is disabled (covered in Step 3)
- Add the bot to the group
- Add the group's chat_id (negative number) to the allowlist
-1001234567890
/telegram:access
6.3 Auto-Start (systemd / pm2)
You don't want to manually start the bot every time the machine reboots. Here are two common auto-start approaches:
Option A: systemd (Recommended for Linux)
sudo nano /etc/systemd/system/claude-telegram.service
[Unit]
Description=Claude Code Telegram Bot
After=network.target
[Service]
Type=simple
User=your-username
Environment=ANTHROPIC_API_KEY=sk-ant-api03-your-key
Environment=HOME=/home/your-username
ExecStart=/home/your-username/.npm-global/bin/claude --daemon
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable claude-telegram
sudo systemctl start claude-telegram
sudo systemctl status claude-telegram
journalctl -u claude-telegram -f
Option B: pm2 (Works on Mac and Linux)
npm install -g pm2
pm2 start "claude --daemon" --name claude-telegram
pm2 startup
pm2 save
pm2 status
pm2 logs claude-telegram
pm2 restart claude-telegram
6.4 CLAUDE.md Custom Instructions
You can create a CLAUDE.md file in your project directory or home directory (~/.claude/CLAUDE.md) to customize Claude's behavior:
# My Preferences
- Please reply in English
- Keep responses concise and to the point
- Add comments to code
- If my question is unclear, ask for clarification instead of guessing
Tip: CLAUDE.md Priority Order
Claude Code reads in order: project directory CLAUDE.md > ~/.claude/CLAUDE.md. Project-level settings override global settings. Telegram conversations use the global ~/.claude/CLAUDE.md by default.
7. Troubleshooting
Bot Not Responding
bun --version
ps aux | grep claude
curl -s "https://api.telegram.org/botYOUR_TOKEN/getMe"
Permission Errors (Mac)
EACCES / Permission denied
The most common permission issue on Mac is having used sudo to install. Solution:
1. Remove what was installed as root: sudo rm -rf /usr/local/lib/node_modules/@anthropic-ai
2. Set npm's global path to your home directory (covered in Step 2)
3. Reinstall as a regular user
Bun not found
ls ~/.bun/bin/bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
API Rate Limit
Voice Messages Not Recognized
pip show faster-whisper
ffmpeg -version
brew install ffmpeg
sudo apt install ffmpeg
8. Conclusion
Congratulations on completing the Claude Code + Telegram setup! You now have a 24/7 personal AI assistant that you can interact with via Telegram anytime, anywhere.
Let's recap what we did:
Install Bun → Install Claude Code → Create Telegram Bot → Configure Plugin → Advanced Setup. The entire process takes about 30-60 minutes (not counting time spent on pitfalls).
Some usage tips:
- Regularly check API usage — especially after adding groups, multiple users will consume quota quickly
- Make use of CLAUDE.md — write your common preferences in it, and the bot will remember
- Monitor daemon status — occasionally check the logs to make sure nothing is wrong
- Keep it updated — Claude Code updates frequently, new versions usually fix many bugs
npm update -g @anthropic-ai/claude-code
If you found this tutorial helpful, feel free to share it with friends who also want to set this up. If you have any questions, feel free to reach out on Telegram.
Happy hacking!