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, Codex, Grok Build or 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).
• 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: <id>, 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. 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.

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