Angelia · Updated 30 October 2026 # Claude Code on WhatsApp Angelia joins WhatsApp as a linked device, like WhatsApp Web, on a second number. Each chat or group you route gets its own session of 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/). You write to that number like to a person, and the answer comes back to the chat. ## Why a second number Link a second, established number, not your personal one. - Angelia ignores what its own account sends. On your personal number it would not hear you, and it would answer as you. - A linked device can read every chat on its account. On a second number, that is only the chats you bring to it. - WhatsApp bans newly created numbers that start acting like robots, usually within hours. A number that has been in use for a while is safer. ## 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 phone with the second number on WhatsApp, to scan the QR code once. - 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 WhatsApp (or both apps). 2. The wizard opens a local page with a live QR code; the terminal shows it too. On the phone with the second number, open WhatsApp › Settings › Linked devices › Link a device and scan it. Do not pick "Link with phone number": WhatsApp currently rejects pairing codes from third-party clients. If the phone asks for a passkey, create it and scan again. 3. Pick a CLI and a folder for the first profile. 4. From your own phone, send the second number a message in the chat it should answer, and confirm it in the wizard. `angelia service install` keeps Angelia running: it starts at login and comes back after a crash. To add WhatsApp to a setup you already have: 1. Add `whatsapp: { auth_dir: ~/.angelia/wa }` to `~/.angelia/workspace/routing.yaml`. 2. Run `angelia accept`. 3. Run `angelia pair` and scan the QR code. 4. Send `/restart` in a chat you own, or run `angelia restart`. 5. From your phone, send the number a message in the chat it should answer. 6. Take that chat's id from `~/.angelia/daemon.log`. 7. Add a route: `{ platform: whatsapp, chat: , profile: main }`. 8. Send `/restart` again, then `/restart confirm` if it lists new rights. ## Groups - Add the second number to a group and route the group to a profile. In a group, the agent answers only when someone mentions it or replies to it. A route with `mention: any` answers every message. - Only the route's owners are heard, unless `allow_from` names others or says `"*"`. Only owners approve commands, change the session or restart. - People appear by phone number or by a `@lid` id (WhatsApp's newer hidden id). `allow_from` and `owners` accept the phone number once WhatsApp has told Angelia which `@lid` is which number. Group ids look like `1203630000…@g.us`. - With onboarding on (`defaults.unmatched: onboard`), an onboarding owner mentions the number in a new group, and Angelia makes a profile for that group: a folder, a starter instruction file and a route. Its agent then asks what the group is for. ## What works Approvals, voice notes, files, long answers and chat commands work the same on WhatsApp and Telegram: [what works from the chat](https://useangelia.com/claude-code/#what-works). What is particular to WhatsApp: - **Voice notes** (tested with Claude Code). An audio file the agent sends back arrives as a real voice note: Angelia converts it to ogg/opus when ffmpeg is installed. - **Files.** Photos, videos and documents up to 20 MB reach the agent. Stickers are not downloaded. The agent sends files back up to 64 MB. - **Long answers** are split into messages of up to 3,500 characters. - **Chat commands.** WhatsApp has no command menu, so type them. ## Security and privacy - WhatsApp messages are end-to-end encrypted to the linked device, which is your Mac. Angelia has no server and keeps no copy of your messages. - Each turn goes to your CLI's model provider, under that CLI's own terms. - The WhatsApp login lives in `auth_dir` (`~/.angelia/wa` by default, mode 700). Whoever holds it holds the WhatsApp account, so every profile's file tools are denied the default folder. - Angelia keeps the last hour of messages it sent (up to 500) in memory, never on disk, so a phone that could not decrypt one can get it again. - `angelia unpair` logs that one linked device out and deletes its login. The phone and its other linked devices are not touched. ## Limits - It needs a second number. - Tested on WhatsApp so far (27 October 2026): Claude Code, Codex, pi and Grok Build. Answering Grok Build's questions from the chat works from Angelia 0.3.23. - Angelia links as an unofficial client, not through the WhatsApp Business API. WhatsApp can ban a number it sees acting like a bot. - macOS only for now, and the Mac must be on. Linux is next. - It is a young project (v0.3), maintained by one person. ## 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 Telegram bot](https://useangelia.com/telegram/) - [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 links the number and 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)