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](https://useangelia.com/claude-code/), [Codex](https://useangelia.com/codex/), [Grok Build](https://useangelia.com/grok/) or [pi](https://useangelia.com/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](https://useangelia.com/docs/reference/#backends-in-detail)). - A bot token. Open [@BotFather](https://t.me/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](https://useangelia.com/claude-code/#what-works). 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](https://useangelia.com/docs/security/) 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](https://useangelia.com/codex/), [Grok Build](https://useangelia.com/grok/) and [pi](https://useangelia.com/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. ## More about Angelia - [Claude Code on WhatsApp and Telegram: sessions, approvals](https://useangelia.com/claude-code/) - [Angelia for Codex: setup, sandbox, approvals and limits](https://useangelia.com/codex/) - [Angelia for Grok Build: setup, approvals and limits](https://useangelia.com/grok/) - [Angelia for pi: setup, sandbox, approvals and limits](https://useangelia.com/pi/) - [Claude Code on WhatsApp](https://useangelia.com/whatsapp/) - [Angelia vs OpenClaw, Hermes Agent and Remote Control](https://useangelia.com/alternatives/) - [Docs](https://useangelia.com/docs/) - [Tools](https://useangelia.com/tools/) - [Guides](https://useangelia.com/guides/) ## Try Angelia ``` curl -fsSL https://useangelia.com/install | sh ``` It checks the release's signature, then a wizard pairs your first chat. Free and open source (MIT). [How it works](https://useangelia.com/) · [Security model](https://useangelia.com/docs/security/) · [GitHub](https://github.com/korengast/angelia) Angelia · open source, MIT [Docs](https://useangelia.com/docs/) · [info@useangelia.com](mailto:info@useangelia.com) · [GitHub](https://github.com/korengast/angelia)