macOS integration: scheduled messages and reminders can be synced to Apple Reminders, and a launchd supervisor runs the bot as a 24/7 daemon with auto-restart.
Speech-to-text provider in the voice transcription fallback chain (OpenAI Whisper → Groq → Deepgram → local whisper-cli), used to transcribe incoming Telegram voice messages.
Text-to-speech provider used to send Claude's replies back as native OGG/Opus voice messages, with automatic fallback to an audio file when voice replies are restricted.
Lets the bot check the user's schedule, create calendar events, and deliver daily briefings from Telegram, with multi-account support and proactive use of calendar context when answering questions.
Used as the primary speech-to-text provider: incoming Telegram voice messages are transcribed with OpenAI Whisper, with automatic fallback to other providers if unavailable.
The core platform for the server: it runs a Telegram bot that receives and replies to text, photos, files, documents, stickers, GIFs and voice messages in DMs and group chats. Supports pairing/group onboarding, forum topics, reply threading and reply/forward context, inline tappable buttons (ask_user), reaction status indicators (read → working → done), message batching, and history/memory persistence across restarts.
Publishes long research answers (3000+ characters) to telegra.ph as Instant View articles; opt-in via TELEGRAPH_ENABLED.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Claude Telegram Supercharged remind me to review the deploy at 5pm and message me on Telegram"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Getting Started • Features • Agentic Mode • Tools Reference • Contributing
https://github.com/user-attachments/assets/51f9f8c4-886d-4aec-bf2a-dddc8ef15cfc
Drop-in upgrade for the official Claude Code Telegram plugin. Install once, get 15+ features the official plugin doesn't have. Built on top of the official plugin -- everything works, just better.
2 minutes to install. Zero config. Your existing bot and pairing keep working.
Install the official plugin first (in Claude Code: /plugin install telegram@claude-plugins-official), then:
curl -fsSL https://raw.githubusercontent.com/k1p1l0/claude-telegram-supercharged/master/install.sh | bashRun it again any time to update. The full walkthrough is in Getting Started.
Security: the only official source is github.com/k1p1l0/claude-telegram-supercharged. This project never ships zip or exe downloads. Copies elsewhere that offer a zip file are malware; please don't run them, and report them to GitHub.
One take in a real chat on a Mac, 52 seconds. A voice message goes in and local whisper transcribes it. Agentic Mode shows each tool call while Claude checks GitHub, and the answer comes back as an ElevenLabs voice message. Then /agents opens the Agents Board. Waits and typing are sped up, and the video shows by how much.
https://github.com/user-attachments/assets/4c5a5968-b5cc-43f1-a756-4282d3eedae9
Official plugin | Supercharged | |
Text, photos, files, stickers | ✅ | ✅ |
Formatted replies, long-message splitting | ✅ | ✅ |
Voice messages | Raw audio file | ✅ Transcribed (OpenAI, Groq, Deepgram or local Whisper) |
Voice replies | ❌ | ✅ ElevenLabs |
Live progress while Claude works | ❌ | |
History and memory that survive restarts | ❌ | ✅ SQLite + memory file |
Knows which message you replied to | ❌ | ✅ Reply context, quotes, forwards |
Questions with inline buttons | ❌ | ✅ |
Scheduled messages and reminders | ❌ | ✅ Also syncs to Apple Reminders |
Google Calendar | ❌ | ✅ |
24/7 daemon with auto-restart | ❌ | ✅ launchd supervisor |
Model routing (Haiku / Sonnet / Opus) | ❌ | ✅ |
Long answers as Telegraph articles | ❌ | ✅ |
Approve permission prompts from Telegram | ✅ | ✅ Buttons or "yes ", plus an auto-approve list |
Live board of sessions, subagents and tokens | ❌ |
Related MCP server: Claude Telegram Supercharged
Feature | What it does |
🎤 Voice Messages | Talk to Claude. Provider fallback chain: OpenAI Whisper → Groq → Deepgram → local whisper-cli. Works from your phone while walking. |
🔊 Voice Replies (TTS) | Claude replies with voice messages via ElevenLabs TTS. OGG/Opus native format. Auto-fallback to audio file if voice is restricted. |
🎤 Auto-transcribe | ALL voice messages in group chats are transcribed, even without mentioning the bot. Configurable via |
Feature | What it does |
📨 Forwarded Messages | Full forwarding context preserved -- Claude sees who originally sent it and from which chat/channel. |
📦 Message Batching | Forward 20+ messages at once -- collected into one batch (5s debounce), auto-summarized instantly, then Claude responds to the whole conversation in one reply. |
📄 Document Support | Send PDFs, DOCX, CSV, TXT, JSON -- Claude downloads, reads, and summarizes. 10MB file size limit. |
🎨 MarkdownV2 Auto-escaping | Special characters auto-escaped server-side -- Claude writes natural text, no manual |
🔤 Incoming Formatting | Bold, italic, strike, underline, spoiler, code, code blocks with language, quotes and hidden links in your messages reach Claude as Markdown, instead of being dropped by Telegram's plain-text |
😎 Sticker & GIF Support | Claude sees stickers and GIFs. Static as images, animated as multi-frame collages. |
📰 Telegraph Instant View | Long research (3000+ chars) published to telegra.ph as Instant View. Disabled by default -- opt-in via |
Feature | What it does |
💬 Message History | SQLite-backed rolling store. Claude has context across restarts. |
🧠 Conversation Memory |
|
🧵 Conversation Threading | Follows reply chains in groups, sees who said what, responds in the correct thread. Up to 3 levels deep. |
📋 Forum Topics | Telegram Forum topics fully supported. Each topic isolated with persistent |
👥 Group Pairing | Add bot to group, mention it, get pairing code. No hunting for numeric chat IDs. |
🎯 Inline Buttons |
|
👍 Reaction Status | 👀 read → 🔥 working → 👍 done. Voice messages get ✍ for transcription. |
Feature | What it does |
⚡ Two-Tier Model Routing | Configurable router: Haiku (fast, 200K), Sonnet (balanced, 1M), or Opus (deep, 1M). Set via |
🛠 Agentic Mode | Watch Claude work: "typing…" the whole time, plus a live "Working… (Ns)" message with Claude's notes and each tool call as it runs. The answer replaces it in place. |
📊 Agents Board |
|
🔄 Daemon Mode | Supervisor auto-restarts Claude on crash or context reset. Memory preserved, zero downtime. |
🛡 Context Watchdog | Auto-restarts when context exceeds 50%, or after 2 hours of uptime, to keep sessions responsive. SQLite history and memory survive restarts. |
🔒 Single-Instance Lock | PID-based lock file prevents duplicate bot instances competing for Telegram updates. |
⏰ Scheduled Messages |
|
📅 Google Calendar | Check schedule, create events, daily briefings from Telegram. Multi-account support. Proactive — Claude uses calendar context when answering. |
📸 Headless Screenshots | Playwright-based page capture -- works in daemon mode where Chrome isn't available. |
✅ Reaction Validation | Client-side emoji whitelist prevents cryptic Telegram API errors. |
🔒 Shell Injection Protection | All subprocess calls use |
📊 Smart Caching | Voice/audio cached between middleware and handlers. No double downloads or transcriptions. |
Default pairing flow for a single-user DM bot. See ACCESS.md for groups and multi-user setups.
Bun -- the MCP server runs on Bun. Install with curl -fsSL https://bun.sh/install | bash.
Open a chat with @BotFather on Telegram and send /newbot. BotFather asks for two things:
Name -- the display name shown in chat headers (anything, can contain spaces)
Username -- a unique handle ending in bot (e.g. my_assistant_bot). This becomes your bot's link: t.me/my_assistant_bot.
BotFather replies with a token that looks like 123456789:AAHfiqksKZ8... -- that's the whole token, copy it including the leading number and colon.
These are Claude Code commands -- run claude to start a session first.
/plugin install telegram@claude-plugins-officialClone this repo and install both the supercharged server and the daemon supervisor:
git clone https://github.com/k1p1l0/claude-telegram-supercharged.git
PLUGIN_DIR=~/.claude/plugins/cache/claude-plugins-official/telegram/$(ls ~/.claude/plugins/cache/claude-plugins-official/telegram/ | sort -V | tail -1)
cp claude-telegram-supercharged/server.ts claude-telegram-supercharged/miniapp.ts $PLUGIN_DIR/
cp -R claude-telegram-supercharged/miniapp $PLUGIN_DIR/
mkdir -p ~/.claude/scripts
cp claude-telegram-supercharged/supervisor.ts ~/.claude/scripts/telegram-supervisor.ts
cp claude-telegram-supercharged/scripts/claude-daemon-wrapper.exp ~/.claude/scripts/claude-daemon-wrapper.exp
chmod +x ~/.claude/scripts/claude-daemon-wrapper.exp
cp claude-telegram-supercharged/scripts/telegram-progress-hook.ts ~/.claude/scripts/telegram-progress-hook.ts/telegram:configure 123456789:AAHfiqksKZ8...Writes TELEGRAM_BOT_TOKEN=... to ~/.claude/channels/telegram/.env. You can also write that file by hand, or set the variable in your shell environment -- shell takes precedence.
The server won't connect without this -- exit your session and start a new one:
claude --channels plugin:telegram@claude-plugins-officialOr use the daemon supervisor for always-on operation with auto-restart and context reset from Telegram (see Daemon Mode):
bun ~/.claude/scripts/telegram-supervisor.tsWith Claude Code running from the previous step, DM your bot on Telegram -- it replies with a 6-character pairing code. If the bot doesn't respond, make sure your session is running with --channels. In your Claude Code session:
/telegram:access pair <code>Your next DM reaches the assistant.
Unlike Discord, there's no server invite step -- Telegram bots accept DMs immediately. Pairing handles the user-ID lookup so you never touch numeric IDs.
Pairing is for capturing IDs. Once you're in, switch to allowlist so strangers don't get pairing-code replies. Ask Claude to do it, or /telegram:access policy allowlist directly.
Important: The official plugin auto-updates and will overwrite your supercharged
server.ts. When the bot suddenly stops working after an update, this is why.
The quickest way to update (also after an official plugin update) is to re-run the one-line installer. To do it by hand:
When the official plugin updates (check for new version directories in ~/.claude/plugins/cache/claude-plugins-official/telegram/):
cd claude-telegram-supercharged
git pull
# Find the current version (e.g. 0.0.4)
PLUGIN_VERSION=$(ls ~/.claude/plugins/cache/claude-plugins-official/telegram/ | sort -V | tail -1)
echo "Updating to version: $PLUGIN_VERSION"
cp server.ts miniapp.ts ~/.claude/plugins/cache/claude-plugins-official/telegram/$PLUGIN_VERSION/
cp -R miniapp ~/.claude/plugins/cache/claude-plugins-official/telegram/$PLUGIN_VERSION/
cp supervisor.ts ~/.claude/scripts/telegram-supervisor.ts
# Copy skills
cp -r skills/* ~/.claude/plugins/cache/claude-plugins-official/telegram/$PLUGIN_VERSION/skills/
# Copy scripts
cp scripts/claude-daemon-wrapper.exp ~/.claude/scripts/claude-daemon-wrapper.exp
cp scripts/telegram-progress-hook.ts ~/.claude/scripts/telegram-progress-hook.tsThen restart your daemon or Claude Code session.
Tool | Purpose |
| Send to a chat. Takes |
| Add an emoji reaction to a message by ID. Only Telegram's fixed whitelist is accepted (👍 👎 ❤ 🔥 👀 🎉 😂 🤔 etc). Also used for status indicators (👀 read → 👍 done). |
| Edit a message the bot previously sent. Supports |
| Send a question with inline keyboard buttons and wait for the user's choice. Takes |
| Retrieve recent message history from a chat. Takes |
| Search message history by text pattern. Takes |
| Clear all message history for a chat. Always confirm with |
| Save a conversation summary to persistent memory. Loaded into Claude's instructions on every startup. Use before |
| Publish long-form content to Telegraph (telegra.ph) and return a URL. Telegram renders it as Instant View -- a native article reader. Takes |
Event | Description |
Text message | Forwarded to Claude as a channel notification with |
Photo | Downloaded to inbox, path included in notification so Claude can |
Emoji reaction | When a user reacts to a bot message, Claude receives a notification with |
Voice message | Downloaded to inbox as |
Audio file | Forwarded audio files ( |
Sticker | Static |
GIF / Animation | Downloaded and converted to a multi-frame horizontal collage so Claude can see the animation content. |
Inbound messages trigger a typing indicator automatically -- Telegram shows "botname is typing..." while the assistant works on a response.
Voice messages and audio files are downloaded to ~/.claude/channels/telegram/inbox/ and automatically transcribed by the server. The transcription text replaces "(voice message)" in the notification, so Claude receives the spoken text directly.
Think of it as Wispr Flow for Claude Code. Open Telegram, hold the mic button, say "refactor the auth middleware to use JWT" -- Claude gets that as text and starts working. No typing, no desktop app needed, works from your phone.
The server tries transcription methods in this order:
OpenAI Whisper API (recommended) -- fastest, highest quality, non-blocking. Set your API key in ~/.claude/channels/telegram/.env:
OPENAI_API_KEY=sk-proj-...Uses whisper-1 by default ($0.006/min). You can switch to a different model:
OPENAI_WHISPER_MODEL=gpt-4o-transcribeNo local install needed. The active transcription method is logged at startup.
whisper.cpp (local fallback) -- brew install whisper-cpp. Fast C++ port, runs fully offline. Requires a model file:
# Download the small multilingual model (465MB, good quality/speed balance)
mkdir -p /usr/local/share/whisper-cpp/models
curl -L -o /usr/local/share/whisper-cpp/models/ggml-small.bin \
"https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin"openai-whisper (local fallback) -- pip install openai-whisper. Python-based, slower but also works offline.
No transcriber -- voice messages are still downloaded and the audio_path is included in the notification, but no transcription is provided.
Local options (2 & 3) require ffmpeg (brew install ffmpeg) for audio format conversion. If you have an OpenAI API key, option 1 is recommended -- it's async (doesn't block the event loop), faster, and more accurate.
When autoTranscribe is enabled (the default), the server transcribes all voice/audio messages in group chats -- even ones that don't mention the bot. This means get_history and the auto-injected context always show the spoken text (prefixed with 🎤) instead of [voice]. Claude gets full conversational context including what people said in voice messages.
To disable (e.g. to save CPU on busy groups):
/telegram:access set autoTranscribe falseTo re-enable:
/telegram:access set autoTranscribe trueClaude can publish long-form content to Telegraph and send it as Instant View links in Telegram -- a native full-screen article reader. Telegraph is disabled by default because posts are publicly accessible by URL.
To enable, add to ~/.claude/channels/telegram/.env:
TELEGRAPH_ENABLED=trueWhen enabled, Claude only uses Telegraph for truly long content (3000+ characters with multiple sections) -- research reports, comprehensive analyses, detailed guides. Regular replies always stay in chat.
When disabled (default):
The create_telegraph_page tool is hidden from Claude
Claude sends all content directly in chat message
This server cannot be deployed
Cloud-hosted MCP server for durable AI memory
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Free hosted MCP server: new Upwork jobs for your agent and Telegram alerts within a minute.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
