telegram-afk
Connects Claude Code sessions to Telegram through a bot, creating one forum topic per session, routing messages between Telegram and the matching session, relaying permission prompts with Allow/Deny buttons, and sending turn updates and optional voice notes.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
telegram-afk
Talk to the Claude Code sessions on your Mac from Telegram, while you're away from the keyboard.
One bot, one forum topic per session. Each session posts its updates in its own topic, and anything you type in a topic goes to that session only. Permission prompts arrive with Allow and Deny buttons, so a session that needs a yes doesn't sit waiting until you're back at your desk.
I built it because I usually have several sessions running, and walking away meant either leaving them stuck or coming back to a wall of "waiting for input". It pairs well with Deckhand, which opens sessions with Telegram switched on one by one, and jarvis-voice, which turns updates into voice notes.
How it fits together
phone (Telegram) <-> tgd daemon (owns the bot, one poller) <-> Unix socket
|-- channel.ts (session "api-server")
|-- channel.ts (session "landing-page")
`-- hook.ts (Stop / idle updates in AFK mode)daemon.ts: the only process that talks to Telegram. Telegram allows one poller per bot token, which is why a single-session plugin can't serve several sessions. It creates a topic per session name, reuses it on restart, queues sends at about one per second and checks every message against your Telegram user ID.channel.ts: a Claude Code channel (MCP server), started once per session. It pushes your Telegram messages into the session, gives Claude areplytool (text and files) and relays permission prompts.hook.ts: Stop and Notification hook. In AFK mode, it posts the end-of-turn summary to the session's topic, unless Claude already replied that turn.ctl.ts:token,pair <CODE>,status,afk on|off,voicetest.
A session's topic is named after its folder. Set CLAUDE_TG_NAME in the session's environment (or in the env of its MCP config) to name it something else. Deckhand does this for you, using the session's title.
Related MCP server: mcp-telegram-claudecode
Setup
You'll need Bun and Claude Code on macOS.
In Telegram, ask BotFather for
/newbot, then turn on Threaded Mode in the bot's settings.Clone and install:
git clone https://github.com/Hari-K-Dev/telegram-afk cd telegram-afk bun installSave the bot token. It's prompted for and never echoed, and it's stored owner-only in
~/.config/claude-tg/.env:bun ctl.ts tokenInstall the background daemon. This fills the placeholders in the template with your paths:
sed -e "s|__BUN__|$(which bun)|" -e "s|__REPO__|$PWD|g" -e "s|__HOME__|$HOME|g" \ telegram-afk.plist.example > ~/Library/LaunchAgents/io.github.hari-k-dev.telegram-afk.plist launchctl load ~/Library/LaunchAgents/io.github.hari-k-dev.telegram-afk.plistDM your bot. It replies with a code that works for 10 minutes. Approve it on the Mac:
bun ctl.ts pair <CODE>Create the MCP config that sessions use:
sed -e "s|__BUN__|$(which bun)|" -e "s|__REPO__|$PWD|g" mcp.json.example > ~/.config/claude-tg/mcp.jsonStart a session with the channel:
claude --mcp-config ~/.config/claude-tg/mcp.json --dangerously-load-development-channels server:telegram-afkConfirm the development-channel warning once per launch. A shell alias helps.
Optional: add
hook.tsas a Stop hook and as a Notification hook (matcheridle_prompt) in~/.claude/settings.jsonfor automatic updates in AFK mode.
If topics in the private chat don't work on your phone, create a private group with Topics on, add the bot as an admin with Manage Topics, and put the group's chat ID in ~/.config/claude-tg/state.json as "group_id".
Phone commands
/sessionslists live sessions/afksends a voice note and update every time a session finishes a turn, and turns the Mac's speakers off/backstops automatic updates and turns the speakers back on/voicetestsends a sample voice note to this topicyes abcde/no abcde, or the buttons, answer a permission prompt
Voice
With jarvis-voice installed (uv sync --extra listen, plus ffmpeg), AFK mode talks:
A finished turn sends a voice note to the session's topic, with the words as its caption. The full text follows, unless the note already said all of it.
A deliberate
replygets a voice note too, but no second copy of the text.A voice message in a topic is transcribed on the Mac, echoed back as
Heard: ..., and reaches that session as text. It can never answer a permission prompt: use the buttons, where nothing can be misheard.
If any of this fails, the text update still goes out. Set JARVIS_BIN if the command isn't at ~/.local/bin/jarvis.
Security
Read this before you install it. A bot that can type into your Claude sessions is a powerful thing to leave lying around.
Who can control your sessions. Only the Telegram account you paired. Every message and button press is checked against that user ID (and chat), so other people, including members of a group the bot sits in, are ignored. Pairing only works in a private chat, needs a code confirmed on the Mac within 10 minutes, and closes for good once you've paired. If state.json is damaged, the daemon stops rather than quietly reopening pairing.
Your Telegram account is the key. Whoever controls it, on any logged-in device including Telegram Desktop and Web, can instruct sessions and approve tool use. Keep two-step verification on.
Forwarded messages are not instructions. If you forward someone else's message into a topic, the session gets it labelled as written by someone else, with a note to treat it as untrusted data. A forwarded "yes abcde" never approves anything. Claude can still be talked into things by clever text, so be careful what you forward to a session with broad permissions.
Telegram is not end-to-end encrypted for bots. Permission previews (which can include commands and file contents), end-of-turn summaries, session titles and any files Claude sends all pass through Telegram's servers. Don't use this for work you couldn't put in a normal Telegram chat.
What stays on your Mac. The token, state and socket live in ~/.config/claude-tg/, which is owner-only (0700, files 0600). Downloads from the phone are removed after a day. The log records timings, IDs and errors, never message text or the token. Any process running as your user can talk to the daemon's socket. That's the same trust level as your shell, so it's fine on a personal Mac.
The development-channel flag. Custom channels need --dangerously-load-development-channels during Claude Code's channels research preview. The flag lets Claude Code load a channel server that isn't on its allowlist, in this case channel.ts from this repo. Only point it at code you've read.
Tests
bun test runs the real daemon and two channel sessions against a fake Bot API. The tests cover pairing, routing, strangers, forwarded messages, permissions, AFK updates and voice notes.
Caveats
Channels only work in interactive sessions, not
claude -p.macOS only for now: the daemon runs under launchd and the voice features expect jarvis-voice.
MIT licensed, see LICENSE.
A personal project with no connection to Anthropic or Telegram. Claude and Claude Code are Anthropic's trademarks.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects Claude Code sessions to Telegram, enabling AI-powered code assistance and file management directly from Telegram chats.88MIT
- AlicenseAqualityDmaintenanceEnables Claude Code to send and receive messages via Telegram for remote interaction and approval of sensitive operations.8575 npm7MIT
- AlicenseNot gradedqualityBmaintenanceEnables running Claude Code sessions from Telegram with group auto-join, voice transcription, reply-quote context, and a restart-proof polling daemon.2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceA remote HTTP bridge that lets Claude Code agents message you on Telegram, ask questions with tap-to-answer buttons, and send files, while your replies are pushed into running sessions as channel events — with per-project topics, message queueing, and tool-approval relay.14 npmMIT