Getting Started • Features • Agentic Mode • Tools Reference • Contributing
https://github.com/user-attachments/assets/51f9f8c4-886d-4aec-bf2a-dddc8ef15cfc
에이전트 강화
게시자가 제공하는 설치 방식입니다. PlugMCP 엔드포인트가 아닙니다.
원격 URL인가요, 내 컴퓨터에서 실행하는 명령인가요? 두 설치 방식의 차이
PlugMCP에서 실행
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
실행게시자 제공
Getting Started • Features • Agentic Mode • Tools Reference • Contributing
https://github.com/user-attachments/assets/51f9f8c4-886d-4aec-bf2a-dddc8ef15cfc
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.
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 | 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.
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.
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
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
/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.
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 decisionTap.ts needsList.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.ts
Then restart your daemon or Claude Code session.
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-transcribe
No 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 false
To re-enable:
/telegram:access set autoTranscribe true
Claude 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=true
When 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):
create_telegraph_page tool is hidden from ClaudeRequires MCP server restart to take effect.
When you clear chat history, Claude first saves a short summary to ~/.claude/channels/telegram/data/memory.md. This file is loaded into Claude's instructions on every startup -- so context from previous sessions is never fully lost.
/clear and Claude Code restartsThe plugin ships with a supervisor script (supervisor.ts) that runs Claude Code as a managed child process. It handles:
~/.claude/channels/telegram/data/restart.signal, the supervisor detects it within 500ms, waits 3 seconds for Claude to finish sending replies, then kills and respawnsIf you followed the Getting Started steps, the supervisor is already installed at ~/.claude/scripts/telegram-supervisor.ts. Just run:
bun ~/.claude/scripts/telegram-supervisor.ts
Extra flags are forwarded to Claude:
bun supervisor.ts --effort high
The supervisor spawns Claude with --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions by default.
In daemon mode you can watch Claude work, the way you would in the terminal:
You: Read the README and check package.json for the scripts
Bot: Working... (14s)
💬 Reading the README to see the install steps.
💻 Bash: Read README intro
💬 Now checking package.json for the scripts.
📖 Read: package.json
✍️ Writing…
Bot: [the answer replaces the Working message]
ask_user question waits for your answer.💭 Thinking… after a tool returns, ✍️ Writing… once it is producing output.ToolSearch aren't listed.The built-in commands answer allowlisted users in DMs. /usage also answers group members in groups the bot is in. /verbose is stored per chat.
How it works. The supervisor passes scripts/telegram-progress-hook.ts to Claude as a PreToolUse, PostToolUse and Stop hook via --settings, so it never runs in your interactive sessions. The hook appends each event to ~/.claude/channels/telegram/data/progress.jsonl, and the server tails that file and edits the Working message (at most one edit per 1.5 seconds). Claude's notes and the thinking/writing phase come from the session transcript. The server's instructions ask Claude to write one short sentence before each tool call.
Config (supervisor environment): TELEGRAM_VERBOSE sets the default level (1). TELEGRAM_AGENTIC_MODE=off turns the hook off.
/agents opens a live board inside Telegram for every Claude Code session on the Mac, not only the daemon:
How it works. The instance that owns the bot runs a small HTTP server on 127.0.0.1:8790. A worker thread reads claude agents --json for the live sessions and the transcripts in ~/.claude/projects for tokens, tool calls and subagents. It reads only new bytes, and only while someone has the board open. Every API request must carry Telegram's signed initData from a user on your allowlist, so the URL shows nothing to anyone else.
Setup. Telegram opens Mini Apps only over HTTPS, so the board needs an HTTPS address that your phone can reach.
The easiest way needs no account:
brew install cloudflared.TELEGRAM_MINIAPP_URL=auto to ~/.claude/channels/telegram/.env./agents.The bot then starts a Cloudflare quick tunnel and puts its address on the /agents button. The address is random and changes when the bot restarts. After a restart, send /agents again, because older buttons stop working.
For a fixed address, use your own HTTPS setup:
tailscale serve --bg 8790. For a public address: tailscale funnel --bg 8790 or a named Cloudflare Tunnel.~/.claude/channels/telegram/.env, for example TELEGRAM_MINIAPP_URL=https://my-mac.tail1234.ts.net. Serve the board at the root of that address, or make the proxy strip the path./agents.Several machines. If you run Claude Code on more than one computer, one board can show all of them. Tap the machine name in the header to switch. Every machine runs this plugin with its own bot.
openssl rand -hex 24, and put the same TELEGRAM_MINIAPP_PEER_TOKEN in the .env of every machine.TELEGRAM_MINIAPP_HOST to that machine's tailnet address, or to :: for all addresses.TELEGRAM_MINIAPP_PEERS=studio=http://studio:8790,laptop=http://laptop:8790./agents.The main board fetches the other machine's data when you select it. The request carries the shared secret, and the board only fetches addresses from TELEGRAM_MINIAPP_PEERS. Plain HTTP is fine inside a tailnet, because Tailscale encrypts the traffic.
Session controls. Admins can act on sessions from the board. If access.json lists no admins, everyone on the allowlist can. Other users get the board read-only.
[Bash] git status.claude --resume <id> continues it./new. The board never signals or messages the session it runs in.On another machine the controls go through the shared secret, unless that machine turned them off. Each user can run 10 actions per minute. Every action goes to the bot's log, without the message text. TELEGRAM_MINIAPP_CONTROL=off makes the board read-only.
If you run several agents that talk to each other, the board can draw them as a small pixel-art town. Each room is a project (plus one hub), each agent is a character in its room, and a new message flies across as an envelope. The plugin does not collect this data itself: it shows whatever a town feed returns.
Set TELEGRAM_MINIAPP_TOWN_FEED (and TELEGRAM_MINIAPP_TOWN_TOKEN if the feed needs one) and restart. The Sessions header then gets a third view next to Board and List. The bot fetches the feed on the server, with a 3 second timeout and a 1 MB limit, keeps only the fields below, and serves the result at GET /api/town with the same Telegram sign-in as the rest of the board. On another machine from TELEGRAM_MINIAPP_PEERS the board shows that machine's town, if it has a feed.
With reduced motion the characters stand still and envelopes appear in place.
The feed is JSON, schema version 1. Times can be ISO strings or epoch seconds or milliseconds. Unknown fields are dropped.
{
"version": 1,
"generated_at": "2026-10-17T10:00:00Z",
"machine": "studio",
"rooms": [{ "id": "hub", "title": "HQ", "kind": "hub" }, { "id": "shop", "title": "shop", "kind": "project" }],
"agents": [{
"name": "sales@shop", "room": "shop", "department": "sales", "role": "Outbound",
"kind": "claude-session", "listening": true, "state": "waiting",
"waiting_for": "approval to send", "activity": "→ claude: batch ready",
"last_in": "2026-10-17T09:58:00Z", "last_out": "2026-10-17T09:59:00Z"
}],
"messages": [{ "id": "42", "from": "sales@shop", "to": "claude", "ts": "2026-10-17T09:59:00Z", "task_id": "7", "preview": "Batch ready" }],
"tasks": [{ "id": "7", "project": "shop", "title": "Send the batch", "state": "open", "owner": "sales@shop", "updated_at": "2026-10-17T09:59:00Z" }]
}
kind is claude-daemon, pi, claude-session or other. state is busy, waiting, idle or offline. messages are newest first, at most 50. A task may also carry a short priority. A task counts as open unless its state is done, closed, completed, cancelled, merged, resolved or archived. Agents and tasks whose room is unknown go to the hub.
The Town can also show a read-only Delegate board under the rooms. The board is not part of this repo: it is an optional, private JavaScript bundle that you put on the machine yourself. Without it the section stays hidden and nothing else changes.
~/.claude/channels/telegram/private/delegate-board.miniapp.js, or the absolute path in TELEGRAM_MINIAPP_DELEGATE_BUNDLE. The path is read once at start; the file is read again when it changes. Files over 3 MB are refused.chmod 700 on the folder and chmod 600 on the file. The file is read through one opened descriptor. It is refused for that request if its size, inode or modification time changes while it is read, or if after the open the path no longer leads to the file that was opened. A same-size write within one tick of the file system's clock can still go unnoticed. On Windows the board is always off./var and /tmp are). The reader trusts them: each one must be owned by you or by root, and no one else may be able to write to it. Your home folder is fine. Someone who can rename or replace a folder above the bundle can race the reader. After the open, the reader checks again that the path leads to the file it opened. That catches some swaps, such as a folder swapped in for the open and back before the check, but each check walks the path again, so it does not rule out a swap and restore timed around the checks. Folders above the bundle that only you or root can change are the real protection.GET /api/delegate-bundle with the same Telegram sign-in as the rest of the board, so only users on the allowlist can download it, even through a public tunnel. It is never cached (Cache-Control: private, no-store). With no file the route answers 404.window.DelegateBoardBundle = { version: 1, mount(el, props) }, where mount returns { update(props), unmount() }. props is { town: { agents, tasks }, theme: "light" | "dark" }, with agents and tasks exactly as GET /api/town returns them. The page calls update on every town refresh and theme change.version hides the section. So does a bundle that throws: while it runs, from a timer or promise it started, in mount, in update, or later. The page tells the bundle's errors from its own by the file or stack trace that an error names. An uncaught error or rejection that names no script (a rejection with a plain value, or an error with no stack) cannot be traced, so from the start of the load on it also turns the board off, even when the page's own code caused it. The page then unmounts the board and does not load the bundle again until the Mini App is reloaded.blob: URL as trusted same-origin code, with the viewer's privileges in the Mini App. It can call every API route the page can, session controls included. The loader is no sandbox. The only check on who gets the bundle is the Mini App's Telegram sign-in and allowlist; there is no separate entitlement check. Only put a bundle you trust at that path. The page's Content-Security-Policy allows blob: scripts for it.The layout and metrics take ideas from Claude-Code-Agent-Monitor.
The page has a view called Needs you next to Board, List and Town. It is one list of what waits for you, with answer buttons. The Board column for sessions that wait on their own prompt is called Waiting on prompt.
telegram-decisions skill (~/.claude/tg-decisions/state.json), live first, then the old queue, then the rest oldest first. Each shows the options of its Telegram card in the same order, Later included. Texts are cut and anything shaped like a token is replaced.~/agent-inbox/tasks.db, opened read-only (TELEGRAM_MINIAPP_TASKS_DB moves the path). They say "Answer in Telegram": the board has no write path to them.9+ above nine), refreshed every 15 s even when another view is open. On the first open of a session the page opens on Needs you when the count is above 0, unless you have already picked a view; the remembered view is not replaced, and the Board is one tap away.not wired.GET /api/needs returns decisions, approvals and inbox, each with its own status (ok, error or not wired) and items, so an empty list is different from a broken source. The page polls every 5 s while the view is on screen. The server keeps a result for at most 2 s.flock on ~/.claude/tg-decisions/.state.lock, the lock the skill's writer holds exclusively, through flock(1) or a python3 -I helper. A writer that holds the lock for more than a few seconds makes the read fail with an error. There is no retry loop.POST /api/needs/answer with {code, version, option} (and project when two projects use the same code) and the usual Telegram sign-in. The server reads the state again and takes the label from it, never from the page. It refuses with a JSON error and reason: 409 stale (the version changed), 409 closed, 409 not_answerable (an old reply-keyboard decision, a card that is not sent yet, or a card that shows an older version), 400 unknown_option, 400 ambiguous, 404 not_found, 503 state_unreadable. When it accepts, it runs the same code as a button tap in Telegram: one row <CODE> <label> with a negative id and reply_to_msg_id = the card, and the card's keyboard becomes the inert done button. A second tap on the same version returns the first answer with already: true and writes no second row.needsList.ts and decisionTap.ts next to server.ts.You can add your own bot commands and map each one to a Claude Code skill. List them in ~/.claude/channels/telegram/commands.json:
{
"commands": {
"standup": { "skill": "daily-standup", "description": "Daily standup summary" },
"report": { "skill": "weekly-report" }
}
}
Send /standup and Claude runs the daily-standup skill. Any text after the command goes to the skill as arguments, for example /standup only the backend team.
/standup@your_bot. If the group requires a mention, a bare /standup is held like any other unmentioned message, and reaches Claude only if a mention follows within 5 seconds.The server skips an entry with a bad name, a built-in name (status, verbose, new, agents) or no skill, and logs it to stderr. Telegram allows 100 commands, which leaves room for 96 of your own.
How it works. In place of /standup, Claude receives Run the "daily-standup" skill with the Skill tool. and an Arguments: line when there are arguments. The notification also carries command and skill attributes. If the daemon restarts before Claude answers, the replayed message gets the same rewrite.
By default the bot asks Telegram for new messages with long polling. In webhook mode Telegram sends each update to the bot over HTTPS instead. Use it on a server with a fixed public address.
127.0.0.1:8790, an HTTPS address that Telegram can reach: tailscale funnel --bg 8790, a named Cloudflare Tunnel or a reverse proxy. Serve it at the root of that address, or make the proxy strip the path. Telegram accepts only ports 443, 80, 88 and 8443.~/.claude/channels/telegram/.env:
TELEGRAM_WEBHOOK=on
TELEGRAM_WEBHOOK_URL=https://bot.example.com
webhook: Telegram posts updates to https://bot.example.com/telegram/webhook.Without TELEGRAM_WEBHOOK_URL the bot uses the board's address from TELEGRAM_MINIAPP_URL. With TELEGRAM_MINIAPP_URL=auto it waits up to 60 seconds for the quick tunnel, and sets the webhook again each time the tunnel gets a new address. Addresses from tailscale serve work only inside your tailnet, so Telegram cannot reach them.
How it works. The instance that owns the bot calls setWebhook with <address>/telegram/webhook, the same update types as polling, and a secret token that is new on every start. The local server takes POST /telegram/webhook and answers 401 to any request without that token. Updates are handled one at a time and in order, as with polling. The bot answers each request within 8 seconds; a slow update, such as a long voice note, keeps running after that. If there is no HTTPS address, or Telegram rejects it, the bot logs why and falls back to polling. When you turn webhook mode off, polling deletes the old webhook first, so there is nothing to clean up. Telegram reports failed deliveries only through getWebhookInfo. The bot checks it 15 seconds after it sets the webhook and then every 5 minutes, and logs each new error.
TELEGRAM_MINIAPP=off turns the board off, but the server keeps running for the webhook route. It also stops the quick tunnel, so set TELEGRAM_WEBHOOK_URL then.
The bot counts each user's messages per day, delivered and blocked, and the tokens (input, output, cache write and cache read) of every turn their messages started. You can cap messages per minute, messages per hour and tokens per day, for everyone or for one user.
/usage shows your numbers for today and the last 7 days, and your limits. Admins also get a line for every user. In a group, it shows only your own numbers.
How it works. Before a message reaches Claude, the server checks the sender's limits. If the sender is over a limit, the message is dropped and counted as blocked. The sender gets one short notice per window, for example Limit reached: 20 messages per hour. Try again in 14 min., and no notice for more messages in the same window. The tokens per day limit lasts until the next midnight UTC. Every Telegram message counts, so 10 forwarded messages count as 10. A reaction that reaches Claude starts a turn too, so it counts as a message, and reactions from a user who is over a limit are dropped.
Tokens come from the session transcript in ~/.claude/projects. The server reads only new bytes, as the Agents Board does. Each API call goes to the user whose Telegram message started the turn, which is the sender of the newest Telegram message in the transcript. Turns typed in the terminal or started by /loop have no owner and aren't counted. Subagent tokens count for the user too. The server finds the transcript from the path that the daemon's progress hook reports. Without the hook, it uses CLAUDE_PROJECT_DIR and CLAUDE_CODE_SESSION_ID, which Claude Code passes to every MCP server.
For limits, tokens = input + output + cache write. Cache reads are shown separately and never count. They make up most of every call and are much cheaper than input, so counting them would make any limit meaningless.
The server keeps stats in messages.db (table usage_daily) for 90 days. It stores the minute and hour windows there too, so a restart or /new doesn't reset them.
Config goes in ~/.claude/channels/telegram/access.json. Every field is optional. A missing value or 0 means no limit, so the bot works as before until you set one.
{
"limits": { "messagesPerMinute": 5, "messagesPerHour": 60, "tokensPerDay": 2000000 },
"userLimits": { "412587349": { "messagesPerHour": 200 } },
"admins": ["628194073"]
}
ask_user)save_memory)clear_history with restart_context: truerestart.signal with a 3-second delayRunning the supervisor in a terminal (or tmux/screen) works for quick sessions, but has a fundamental problem on macOS: the system suspends background processes aggressively. When you close the lid, switch users, or the Mac goes to sleep, macOS sends SIGSTOP to terminal processes — your bot goes silent until you open the lid again. tmux/screen don't help because they run in userspace and get suspended too.
launchd is Apple's native process manager — the same system that keeps Spotlight, Time Machine, and iCloud running. It operates at the OS level, outside of any terminal session, so it:
caffeinate -s to prevent system sleepCreate ~/Library/LaunchAgents/com.user.claude-telegram.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.claude-telegram</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/caffeinate</string>
<string>-s</string>
<string>/path/to/bun</string>
<string>/Users/YOU/.claude/scripts/telegram-supervisor.ts</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/Users/YOU/.claude/channels/telegram/data/supervisor-stdout.log</string>
<key>StandardErrorPath</key>
<string>/Users/YOU/.claude/channels/telegram/data/supervisor-stderr.log</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/path/to/bun/dir:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>
<key>WorkingDirectory</key>
<string>/Users/YOU</string>
<key>ProcessType</key>
<string>Background</string>
<key>ThrottleInterval</key>
<integer>10</integer>
</dict>
</plist>
Replace /path/to/bun with your bun path (which bun) and /Users/YOU with your home directory.
Don't override
HOMEin the plist. The wrapper runs claude from~/.claude-telegram-daemon, because a cwd of$HOMEmakes Claude Code drop the telegram plugin. To use another directory, setTELEGRAM_DAEMON_CWDinEnvironmentVariables. If the daemon misbehaves, see Daemon Troubleshooting.
Important: Both
RunAtLoadandKeepAliveshould be set to<true/>for hands-off operation.RunAtLoadstarts the daemon automatically on login/boot.KeepAlivetells launchd to restart the process if it exits unexpectedly. Setting either to<false/>means you'll need to manually start the daemon or it won't recover from crashes.
Start the daemon:
launchctl load ~/Library/LaunchAgents/com.user.claude-telegram.plist
Stop the daemon:
launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist
Check if it's running:
launchctl list | grep claude-telegram
A running daemon shows its PID in the first column. A 0 in the status column means it exited cleanly; non-zero means it crashed (launchd will restart it).
View logs:
tail -f ~/.claude/channels/telegram/data/supervisor-stderr.log
Restart (reload config after editing the plist):
launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist
launchctl load ~/Library/LaunchAgents/com.user.claude-telegram.plist
Remove completely (stop + delete):
launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist
rm ~/Library/LaunchAgents/com.user.claude-telegram.plist
Use the built-in monitor skill from any Claude Code session:
/telegram:monitor
Shows a live dashboard: process status for all components, launchd state, recent logs, MCP health, remote control URL (watch the daemon live in your browser), and lock file status.
You can also monitor manually:
# Live supervisor logs
tail -f ~/.claude/channels/telegram/data/supervisor-stderr.log
# Quick alive check
ps aux | grep "channels.*telegram" | grep -v grep && echo "ALIVE" || echo "DEAD"
# Find the remote control URL (open in browser to watch the daemon live)
strings ~/.claude/channels/telegram/data/supervisor-stdout.log | grep "session_" | tail -1
launchd (OS-level)
└── caffeinate -s (prevents system sleep)
└── supervisor.ts (manages Claude lifecycle)
└── claude --channels plugin:telegram (the actual bot)
Note:
caffeinate -sprevents sleep only when connected to power. On battery with the lid closed, macOS will eventually sleep regardless. For true 24/7 uptime on battery, consider running on a server instead.
One session can run several bots, for example a personal bot and a team bot. Each bot keeps its own chats and history, and Claude answers through the bot that got the message.
Add the extra tokens to ~/.claude/channels/telegram/.env, separated by commas:
TELEGRAM_BOT_TOKEN=123456789:AAH... # primary bot
TELEGRAM_EXTRA_BOT_TOKENS=987654321:AAF...,555555555:AAE...
Restart the daemon or the session. The log shows one polling as @... line per bot. Without TELEGRAM_EXTRA_BOT_TOKENS, the server behaves exactly as before.
How it works. Every inbound message reaches Claude with a bot attribute: the username of the bot that received it. Claude passes it back as the bot parameter of reply, react, edit_message, ask_user, voice_reply, create_telegraph_page, get_history, search_messages and clear_history. When a call has no bot, the server uses the bot that last received a message from that chat, or the primary bot if there is none. This matters for DMs, because a private chat has the same chat_id (the user's id) on every bot.
History is stored per bot, so get_history for one bot never shows another bot's conversation with the same person. Messages from before the upgrade belong to the primary bot. Each bot polls under its own lock in ~/.claude/channels/telegram/data/: the primary keeps telegram.lock, and each extra bot gets telegram-<hash>.lock. A second session runs MCP-only for every bot that another session already polls.
Access. All bots read the same access.json. An extra bot uses the primary's allowlist, groups and DM policy unless you give it its own under bots, keyed by its username:
{
"allowFrom": ["412587349"],
"bots": {
"team_bot": { "allowFrom": ["412587349", "628194073"], "dmPolicy": "allowlist" }
}
}
ACCESS.md has the details, including how pairing works for an extra bot.
Primary bot only. A few features stay on the primary bot: Agentic Mode progress (the Working message and the typing refresh), permission prompts and yes <id> / no <id> answers, the /status, /verbose, /new and /agents commands with the Mini App, scheduled jobs, and webhook mode. On an extra bot, /new and the other primary-only commands reach Claude as ordinary text. With TELEGRAM_WEBHOOK=on, the primary bot gets its updates by webhook (the log shows webhook mode as @...) and the extra bots keep long polling, so they need no public address.
Every bot. Custom commands and /usage work on every bot. Each bot's DM menu lists /usage and the commands from commands.json; the primary bot also lists its own built-in commands. In a group, /standup@team_bot runs only on @team_bot. Usage stats and limits count each Telegram user across all bots, so messages to any bot use the same per-minute, per-hour and per-day budget. limits, userLimits and admins stay at the top level of access.json and have no per-bot override.
The plugin supports group chats with smart conversation threading -- Claude can follow reply chains, see who said what, and respond in the correct thread.
1. Disable privacy mode in BotFather
By default, Telegram bots in groups only see commands and messages that mention them. For full thread tracking, disable privacy mode:
/mybots → select your botIf you prefer to keep privacy mode on, the bot will still work -- it just won't see messages that don't mention it, so thread tracking will be incomplete.
2. Add the bot to a group
Add your bot to any Telegram group like a normal member.
3. Pair the group (automatic)
Just send a message in the group mentioning your bot (e.g. @your_bot hello). The bot replies with a 6-character pairing code -- same flow as DM pairing:
/telegram:access pair <code>
That's it. The group is registered automatically with requireMention: true (bot only responds when mentioned or replied to).
To let it respond to all messages:
/telegram:access group update -100XXXXXXXXXX requireMention false
Manual alternative: If you already know the group's numeric ID (starts with
-100...), you can register directly with/telegram:access group add -100XXXXXXXXXX. Ways to find the ID: check the bot's stderr logs, open web.telegram.org (ID is in the URL), or forward a group message to @RawDataBot.
4. Restart Claude Code
claude --channels plugin:telegram@claude-plugins-official
reply_to_text and reply_to_user showing what was replied tothread_context in the notificationIf your supergroup has Topics enabled, the plugin forwards thread_id (Telegram's message_thread_id) and passes it through to replies -- keeping conversations in their correct Forum topic automatically. Topic IDs are persisted in SQLite so context is preserved across restarts.
/stop <task id>, /stopall, /resume <task id>, /resume all, /pause, /stops, /auto (on [hours], off, status, undo <id>, stop, confirm <n>) and /goal, /goals (new ..., <id>, done, stop, pause, resume, confirm) are sent to the agent-harness Telegram router (routerHook.ts). /goal and /goals typed by the owner are consumed by this hook and are not forwarded to the model. /stops is this bot's name for the router's status command, because /status already shows the bot's own state.
/status and commands tagged for another bot (/stopall@otherbot) follow the normal flow.AGENT_HARNESS_ROUTER sets the router file. Default: ~/Projects/agent-harness/telegram-router.ts. The router reads the plugin's access.json and needs its own opt-in file (~/agent-inbox/telegram-router.json).AGENT_HARNESS_STATUS_TEXT sets the text sent to the router for /stops. Default: /stops, the router's status command./auto status, /goals or /stops)./stopall replies with Confirm and Cancel buttons (stp:c:<id>:<generation> and stp:x:<id>:<generation>, 25 bytes at most). A tap re-checks the allowlist, runs the same router command and replaces the message with the result, keeping only the follow-up buttons the router returns (such as Undo). A tap from anyone else only gets a callback answer and the message is left alone. The router rejects an old or used confirm./auto and /goal use their own short prefixes: aut:c:<n> / aut:x:<n> (confirm, cancel), aut:u:<id> (Undo), aut:s (/auto stop), gol:c:<n> / gol:x:<n> (confirm, cancel), gol:s:<id> (/goal stop), all 15 bytes at most. They follow the same rules as stp:: the tapper is re-checked, the token is never trusted, and the router rejects stale taps.Full access control docs in ACCESS.md -- DM policies, groups, mention detection, delivery config, skill commands, and the access.json schema.
Quick reference: Default policy is pairing -- DMs and groups both use the pairing flow. For DMs, message the bot to get a code. For groups, add the bot and mention it to get a code. Then /telegram:access pair <code> approves either. ackReaction only accepts Telegram's fixed emoji whitelist.
If your session doesn't skip permissions, Claude Code sends each approval request to Telegram. Every allowlisted DM gets a message like 🔐 Permission: Bash with See more, ✅ Allow and ❌ Deny buttons. You can also reply yes <id> or no <id> with the five-letter id from the message. Only allowlisted users can answer, and a request can be answered once; every copy of the prompt then shows the outcome. Group members can't approve.
To skip the round-trip for tools you always allow, list them in access.json:
{ "autoApproveTools": ["Read", "Grep", "Glob"] }
The daemon runs with --dangerously-skip-permissions, so it never asks. This is for sessions you start without that flag.
The bot can react to incoming messages with an emoji to signal it received and is processing them. This is controlled by the ackReaction field in access.json:
{
"ackReaction": "👀"
}
Reaction flow:
Telegram only keeps one bot reaction per message, so each new reaction replaces the previous — creating a natural status progression.
Note: ackReaction is not set by default. To enable it, add it to your ~/.claude/channels/telegram/access.json. It only accepts emoji from Telegram's fixed reaction whitelist. Common choices: 👀, ⚡, 🔥.
Every message flowing through the bot is captured in a local SQLite database and persisted across restarts. Claude gets context without asking users to repeat themselves.
~/.claude/channels/telegram/data/messages.db
How it works:
INSERT OR REPLACE dedupget_history retrieves up to 200 messages with pagination; search_messages does substring searchTelegram's Bot API exposes no native history endpoint -- bots only see messages in real-time. We solve this with a local SQLite message store (see Message History below). Every message flowing through the bot is captured and persisted, giving Claude full context across restarts via get_history and search_messages tools. History is available from when the bot joined the chat.
Photos and voice messages are downloaded eagerly on arrival -- there's no way to fetch attachments from historical messages via the Bot API.
MarkdownV2 formatting
Emoji reaction tracking
Ask User inline buttons
Reaction status indicators (👀 → 🔥 → 👍)
Voice & audio messages with whisper transcription
Auto-transcription in history (configurable)
Sticker & GIF support
Emoji reaction validation
Conversation threading
Forum topic support with persistent thread_id
Group pairing flow
Message history buffer (SQLite)
Session management (clear_history + save_memory)
Conversation memory persistence
Shell injection protection (spawnSync)
Smart media caching (no double downloads)
Daemon mode supervisor (auto-restart + context reset from Telegram)
Telegraph Instant View for long-form content
OpenAI Whisper API with local fallback
Agentic Mode: live progress, typing indicator, in-place answers
Remote permission approval (inline buttons, text replies, auto-approve list)
Agents Board Mini App (/agents): live sessions, subagents, context use and tokens per hour
Custom commands (commands.json): bot commands that run Claude Code skills
Webhook mode: alternative to polling for production deployments
Rate limiting & usage stats (/usage): messages and tokens per user, limits per minute, hour and day
Multi-bot support: several bots from one server instance, with per-bot history and optional per-bot access
Scheduled messages: one-time, repeating and cron jobs
Agents Board session controls: read, send, new task, stop and end sessions from Telegram
This is a community project. We want your help!
git checkout -b feature/your-feature)Apache 2.0 -- Same as the original. See LICENSE.
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-li
개요
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.
도구
아직 도구 목록이 없습니다. 원격 서버는 첫 상태 확인 후에 도구 목록이 생깁니다.
FAQ
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
이 레코드에는 필수 환경 변수가 등록되어 있지 않습니다.
Claude Telegram Supercharged은(는) stdio를 통해 로컬에서 실행됩니다.
마지막 확인: 2026-11-17. 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.