Angelia

Angelia · Updated

Claude Code on WhatsApp and Telegram: sessions and approvals from your phone

Angelia connects the Claude Code on your Mac to WhatsApp and Telegram. Each chat gets its own Claude Code session, in its own folder. Your CLAUDE.md, settings, skills, MCP servers and hooks work there as they do in your terminal. Angelia runs no model of its own: Claude Code does the work, under your own claude.ai login.

What Angelia does for Claude Code

What you need

Set it up

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

The first line checks the release's signature, installs Angelia and starts a setup wizard (read the script). The wizard asks for Quick (one chat, one folder) or Advanced (several profiles), then Telegram, WhatsApp or both. Pick Claude Code as the CLI, then send the bot (or the second number) a message from your phone to pair the chat. The second line keeps Angelia running.

The agent works in its profile's folder, not in your current repo. To let it work on a repo, list the repo in the profile's add_dirs in ~/.angelia/workspace/routing.yaml:

profiles:
  main: { cwd: ~/.angelia/workspace/profiles/main, permission_mode: acceptEdits, add_dirs: [~/code/my-app] }

Then accept the change to the routing table and compile the profile's rules. angelia compile refuses while routing.yaml has changes you have not accepted, so accept first:

angelia accept
angelia compile main --write

Send /restart in the chat. Angelia checks the routing table first. If the restart would give the profile new rights, it lists them; then send /restart confirm. Every step, in more detail: how to control Claude Code from your phone.

What works from the chat

Approvals

Under permission_mode: acceptEdits, Claude Code edits files on its own and asks before other commands. The question comes to the chat:

🔐 Bash: npm test
Reply "yes 6b480a6f" or "no 6b480a6f".

An owner answers yes 6b480a6f and the turn goes on. No answer in ten minutes means no. In a group, other members can talk to the agent but cannot approve. The mode is Claude Code's own: default, acceptEdits, plan or bypassPermissions. sandbox: true on the profile turns on Claude Code's own sandbox, which limits every program the agent runs, not only its file tools. With pi, approvals come to the chat the same way, and with Grok Build from Angelia 0.3.23. Codex runs every command in its own sandbox and asks only when it needs more than the sandbox allows. More in notifications and approvals on your phone.

Voice notes

A voice note reaches Claude Code as [voice note: path]. Claude Code runs angelia transcribe <path>, which prints the text. Whisper runs on your Mac, so the audio stays there, and it detects the language by itself. For a spoken answer, angelia speak "<text>" makes an audio file with the voice built into macOS, and the agent sends it back as a voice note.

Photos and files

A photo or document you send lands in the profile's .inbox/ folder, up to 20 MB, and Claude Code gets a [file: path] line. It sends files back with angelia send-media: an image, a video, a voice note or a document. Every path is checked first: never a credential location, never another profile's folder.

Long answers

Short progress lines arrive while Claude Code works, then the answer. A long answer is split at paragraph breaks into messages of up to 4,000 characters on Telegram and 3,500 on WhatsApp. A code block cut in two gets its ``` marks closed and opened again, so each part reads whole. The chat shows "typing" while a turn runs. Angelia sends at most 10 messages a minute per platform by default (max_out_per_min), and progress lines always leave room for the answer and for approvals.

Chat commands

/new, /stop, /status, /resume, /model, /effort, /restart and the others /help lists are answered by Angelia, without spending a token. Any other slash command goes to Claude Code, so /compact or your own commands work from the chat too. Only owners can send them, except /status and /help. When Claude Code hits a usage limit, the chat shows the limit and what to do: /model opus or /model sonnet for this session, /model default once the limit resets.

From the chat to your desk, and back

The Claude app, too

Set tui: true on a profile and install tmux (3.7 or newer recommended; older versions get a warning). The profile then runs Claude Code as a real interactive session in tmux, so it shows up in the Claude app through Remote Control, and you can carry on there. What you type in the app stays in the app; it does not go back to the chat. Trade-offs in ADR 0008.

Scheduled turns

A profile lists jobs in angelia-jobs.yaml in its folder: a schedule and a prompt, a message or a command. angelia jobs install turns each into a LaunchAgent, so macOS runs the timer and the answer lands in the chat. The 24/7 guide covers sleep settings and reboots.

Limits

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 · Reference · GitHub