by k1p1l0
Supercharged Claude Code Official Telegram plugin — threading, voice messages 2 ways, stickers, GIFs, reactions, MarkdownV2 & more. Drop-in replacement.
# Add to your Claude Code skills
git clone https://github.com/k1p1l0/claude-telegram-superchargedGuides for using mcp servers skills like claude-telegram-supercharged.
Getting Started • Features • Tools Reference • Contributing
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.
| 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 autoTranscribe. |
| 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 escaping needed. | | | Claude sees stickers and GIFs. Static as images, animated as multi-frame collages. | | | Long research (3000+ chars) published to telegra.ph as Instant View. Disabled by default -- opt-in via . |
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
\.TELEGRAPH_ENABLED=true| Feature | What it does |
| --- | --- |
| 💬 Message History | SQLite-backed rolling store. Claude has context across restarts. get_history + search_messages tools. |
| 🧠 Conversation Memory | /clean saves a summary before clearing. Memory persists across sessions. Claude never forgets. |
| 🧵 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 thread_id. |
| 👥 Group Pairing | Add bot to group, mention it, get pairing code. No hunting for numeric chat IDs. |
| 🎯 Inline Buttons | ask_user tool -- tappable buttons for confirmations and choices. |
| 👍 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 TELEGRAM_ROUTER_MODEL. Complex tasks auto-escalate to Opus via subagents. |
| 🔄 Daemon Mode | Supervisor auto-restarts Claude on crash or context reset. Memory preserved, zero downtime. |
| 🛡 Context Watchdog | Auto-restarts when context exceeds 70% to prevent unresponsive sessions. SQLite history and memory survive restarts. |
| 🔒 Single-Instance Lock | PID-based lock file prevents duplicate bot instances competing for Telegram updates. |
| 🖥 Daemon Management | /telegram:daemon start\|stop\|restart\|status\|logs -- full lifecycle. /telegram:monitor for health dashboard with remote control URL. |
| ⏰ Scheduled Messages | schedule tool for reminders and recurring tasks. "at" (one-shot) and "every" (interval) types. Persists across restarts. |
| 📅 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 spawnSync with array args. No shell interpretation. |
| 📊 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.
curl -fsSL https://bun.sh/install | bash.Open a chat with @BotFather on Telegram and send /newbot. BotFather asks for two things:
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-official
Clone this repo and install both the supercharged server and the daemon supervisor:
git clone https://github.com/k1p1l0/claude-telegram-supercharged.git
cp claude-telegram-supercharged/server.ts ~/.claude/plugins/cache/claude-plugins-official/telegram/0.0.1/server.ts
mkdir -p ~/.claude/scripts
cp claude-telegram-supercharged/supervisor.ts ~/.claude/scripts/telegram-supervisor.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-official
Or use the daemon supervisor for always-on operation with auto-restart and context reset from Telegram (see Daemon Mode):
bun ~/.claude/scripts/telegram-supervisor.ts
With 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.
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 ~/.claude/plugins/cache/claude-plugins-official/telegram/$PLUGIN_VERSION/server.ts
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
Then restart your daemon or Claude Code session.
| Tool | Purpose |
| --- | --- |
| reply | Send to a chat. Takes chat_id + text, optionally reply_to (message ID) for native threading, files (absolute paths) for attachments, and parse_mode (MarkdownV2/HTML/plain, defaults to MarkdownV2). Images (.jpg/.png/.gif/.webp) send as photos with inline preview; other types send as documents. Max 50MB each. Auto-chunks text; files send as separate messages after the text. Returns the sent message ID(s). |
| react | Add an emoji reaction to a message by ID. Only Telegram's fixed whitelist is acc