Angelia · Updated 30 October 2026

Claude Code Telegram bot

Angelia connects a Telegram bot of your own to the coding agent CLI on your Mac: Claude Code, Codex, Grok Build or pi. Each chat you route gets its own session, in its own folder. Telegram is the quickest way to start: a bot is free, and @BotFather makes one in a few messages.

What you need

• A Mac with Node 22.23.4+, 24.22.1+ or 26.12.1+ and git.
• A supported CLI, installed and signed in: Claude Code 2.1.270+, Codex 0.157+, Grok Build 1.0.13+ or pi 0.80.4+ (backends).
• A bot token. Open @BotFather in Telegram, send /newbot, pick a name, and keep the token it gives you.
• Optional: brew install openai-whisper ffmpeg for voice notes.

Set it up

curl -fsSL https://useangelia.com/install | sh
angelia service install

1. The installer checks the release's signature and starts the setup wizard. Pick Quick (one chat, one folder) or Advanced, then Telegram.
2. Paste the bot token. It is stored on your disk, in ~/.angelia/env (mode 600), never in a chat.
3. Pick a CLI and a folder for the first profile.
4. Send your bot any message from your phone. The wizard shows who wrote and asks you to pair that chat.

angelia service install keeps Angelia running: it starts at login and comes back after a crash. Now send the bot "what is in this folder?". The agent answers from the profile's folder, on your Mac.

Groups and topics

• Make the bot a group admin. Otherwise Telegram's privacy mode hides plain @mentions from it, and it will not answer.
• In a group, the agent answers only when someone mentions the bot or replies to it. A command tapped in the group's menu, such as /status@yourbot, counts as a mention. A route with mention: any answers every message.
• Only the route's owners are heard, unless allow_from names others by their numeric user id, or says "*". Only owners approve commands, change the session or restart.
• A direct chat's id is your numeric user id. A group's id is negative and starts with -100. Both appear in ~/.angelia/daemon.log the first time a chat that is not in the routing table writes.
• A route can name one forum topic with thread:. That topic then has its own profile and session, apart from the rest of the group.
• Messages sent as a channel or by an anonymous group admin are ignored: Angelia cannot tell who sent them.

What works

Approvals, voice notes, files, long answers and chat commands work the same on Telegram and WhatsApp: what works from the chat. What is particular to Telegram:

• Voice notes (tested with Claude Code). An audio file the agent sends back arrives as a voice message when it can be converted to ogg/opus (ffmpeg).
• Files. Photos, videos and documents up to 20 MB, the Bot API's limit, reach the agent. The agent sends files back up to 50 MB.
• Long answers are split into messages of up to 4,000 characters.
• A command menu. Angelia's chat commands are listed in Telegram's command menu. The menu is set in routed chats only, so a stranger who opens the bot does not see it.
• Strangers get nothing. A chat that is not in the routing table gets no reply. ~/.angelia/daemon.log gets one line with its chat id.

Privacy

Angelia has no server. It reads the bot's updates from Telegram directly, from your Mac. Telegram keeps bot messages on its servers: bot chats are not end-to-end encrypted. Each turn goes to your CLI's model provider, under that CLI's own terms. The security model has the rest.

Limits

• Angelia reads the bot's updates by long polling, and Telegram allows one reader per token. Give Angelia a bot of its own, not one another program also uses.
• Answers are sent as plain text. Markdown marks in an answer show as typed.
• macOS only for now, and the Mac must be on. Linux is next.
• Tested on Telegram so far: Claude Code. Codex, Grok Build and pi on Telegram are not tested yet.
• It is a young project (v0.3), maintained by one person.
• To remove the bot itself after you uninstall Angelia, send /deletebot to @BotFather.

curl -fsSL https://useangelia.com/install | sh