Agent Orchestration
Plugin
claude-telegram-supercharged
Run Claude Code 24/7 from Telegram.
Plugin Signal74/100Solid
maintained98
capable43
documented100
adopted46
Install
$ npx -y skills add k1p1l0/claude-telegram-supercharged --agent claude-code
Stats
138
Stars
23
Forks
Active
Maintenance
TypeScript
Language
Apache-2.0
License
4d ago
Last commit
7mo ago
Created
3h ago
Added
What's inside
Skill(7 skills)
/accessManage Telegram channel access — approve pairings, edit allowlists, set DM/group policy. Use when the user asks to pair, approve someone, check who's allowed, or change policy for the Telegram channel./calendarGoogle Calendar integration — check schedule, create events, daily briefings, proactive reminders. Triggers on "what's on my calendar", "add to calendar", "schedule a meeting", "when am I free", "daily briefing", or any calendar-related request./configureSet up the Telegram channel — save the bot token and review access policy. Use when the user pastes a Telegram bot token, asks to configure Telegram, asks "how do I set this up" or "who can reach me," or wants to check channel status.
README
Getting Started • Features • Agentic Mode • Tools Reference • Contributing
https://github.com/user-attachments/assets/51f9f8c4-886d-4aec-bf2a-dddc8ef15cfc
Claude Telegram Supercharged
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 in one line
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 | bash
Run 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.
Live demo
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 vs Supercharged
| 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 | ❌ | ✅ Agentic Mode |
| History and memory that survive restarts | ❌ | ✅ SQLite + memory file |
| Knows which message you replied to | ❌ | ✅ Reply context, quotes, forwards |
| Questions with inline buttons | ❌ | ✅ ask_user |
| 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 | ❌ | ✅ /agents Mini App |
Features
Voice & Audio
| 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. |
Messages & Media
| 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. |
| 🔤 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 text field. Captions and replied-to messages too. |
| 😎 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 TELEGRAPH_ENABLED=true. |
Conversations & Groups
| 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. |
Daemon & Infrastructure
| 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 (change the target with TELEGRAM_ESCALATION_MODEL). |
| 🛠 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. /verbose 0|1|2, /status, /new. Details |
| 📊 Agents Board | /agents opens a Mini App in Telegram: every Claude Code session on the Mac, its subagents, context use, tokens per hour and the latest tool calls. Details |
| 🔄 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 | 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. |
Getting Started
Default pairing flow for a single-user DM bot. See ACCESS.md for groups and multi-user setups.
Prerequisites
- Bun -- the MCP server runs on Bun. Install with
curl -fsSL https://bun.sh/install | bash.
1. Create a bot with BotFather
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.
2. Install the official plugin
These are Claude Code commands -- run claude to start a session first.
/plugin install telegram@claude-plugins-official
3. Apply the supercharged version
Clone 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 claude-telegram-supercharged/decisionTap.ts claude-telegram-supercharged/needsList.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
4. Give the server the token
/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.
5. Relaunch with the channel flag
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
6. Pair
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.
7. Lock it down
File tree
FAQ
claude-telegram-supercharged is a Claude Code plugin with 7 hand-picked skills, indexed on Flowy in the Agent Orchestration category. Install it with the command on its page. It includes access, calendar, configure. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is claude-telegram-supercharged?
- Run Claude Code 24/7 from Telegram. Drop-in upgrade for the official plugin: voice notes both ways, a self-healing daemon, memory across restarts, and Agentic Mode (watch every tool call live). One-line install.
- How do I install claude-telegram-supercharged?
- Run these in Claude Code: npx -y skills add k1p1l0/claude-telegram-supercharged --agent claude-code. Then prompt normally.
- Does claude-telegram-supercharged auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is claude-telegram-supercharged free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it