Angelia

Your coding agent. Your personal assistant. The coding agent CLI you already trust becomes the brain of your personal assistant. You reach it from WhatsApp or Telegram; it runs on your own Mac.

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

Website | Docs | Releases

It works with your files, your tools and the subscription you already pay for. Give each part of your life its own chat and its own folder, and each one gets its own instructions and memory.

Angelia runs no model of its own. It carries messages, files and approvals between your chats and your agent, and nothing else. Bring the CLI you use, keep its skills and MCP servers, and switch any time: see Backends.

In Greek myth Hermes carried the words of the gods. His daughter Angelia (Ἀγγελία, message, tidings) inherited only the message itself: not the wisdom in it, not the decision behind it, just the promise that what was said in one place would arrive whole in another. That is the entire ambition of this project.

---

Quick start

macOS

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

https://github.com/user-attachments/assets/2532dfea-d4f9-4d07-830d-d1fa084e0690

The installer checks Node, fetches the newest release, verifies its signature (release key SHA256:74hZgwt/ABiUQz6C9A1r7hpHZtCRq1KfC1KvvCR1ys0), installs it and starts the setup wizard. The wizard asks for a bot token and which CLI to use, makes your first profile, and pairs the chat when you send the bot a message.

You need:

• Node 22 or newer and git (it comes with the Xcode command line tools).
• A supported coding agent CLI, installed and signed in to your own account. See Backends.
• A Telegram bot. Open @BotFather, send /newbot and keep the token ready. It is stored on your disk, never in a chat.
• Optional: brew install openai-whisper ffmpeg for voice notes, and brew install tmux (3.7+) to run a Claude Code profile in its full screen, so the chat also shows up in the Claude app.

After installation:

angelia service install   # keep it running: starts at login, comes back after a crash

Then send "what is in this folder?" to your bot. The agent answers from the profile's folder.

Linux and Windows: not yet. The daemon is plain Node, but the service, the timers and the built-in voice use macOS today. Linux with a systemd unit is next.

---

Getting started

angelia init                         # setup wizard: bot token, CLI, first profile, pair the chat
angelia status                       # what is running, and which chats are warm
angelia check-config                 # validate routing.yaml and warn about risky combinations
angelia profiles                     # every profile and the chats routed to it
angelia profile add <platform:chat>  # a new profile and route for a chat, by hand
angelia compile <profile> --write    # write a profile's tools and deny rules into its CLI settings
angelia pair                         # link WhatsApp by QR
angelia jobs install                 # turn each profile's angelia-jobs.yaml into timers
angelia send <chat> <text>           # post into a chat from any script
angelia turn <chat> <text>           # ask that chat's agent; the answer lands in the chat
angelia update                       # install the newest signed release; your profiles are not touched
angelia guide                        # the manual your agent reads before it changes the setup

📖 Full reference →

---

How it works

Four words, and one file that ties them together.

• Profile. A folder where your agent works: its instruction file, its memory, its settings. The agent opens there exactly as in your terminal.
• Route. One line that sends one chat to one profile.
• Session. Every chat keeps its own conversation with the agent, across restarts.
• Owner. Who may approve what the agent wants to run and use the chat's commands. In a direct chat, that is you.

profiles:
  coding: { cwd: ~/.angelia/workspace/profiles/coding, permission_mode: acceptEdits, add_dirs: [~/code] }
  house:  { cwd: ~/.angelia/workspace/profiles/house,  permission_mode: acceptEdits }

routes:
  - { platform: telegram, chat: 111111111,      profile: coding }
  - { platform: telegram, chat: -1001234567890, profile: house, owners: [111111111], allow_from: [111111111, 333333333] }

telegram: { token_env: TELEGRAM_BOT_TOKEN }

The wizard writes this file for you, in ~/.angelia/workspace/routing.yaml. With onboarding on, a new chat adds its own profile and route the first time you mention the bot there.

---

Chat commands

Answered by Angelia itself, without spending a token. Registered in Telegram's command menu.

Owners only, except /help and /status. Any other slash command goes to your CLI, so its own commands (/compact, a custom one) work from the chat too.

From the terminal to the chat

Working in Claude Code at your desk and want to go on from your phone? Type /angelia-handoff in that terminal session. angelia compile --write installs the command for every terminal session on the machine. Where it goes depends on the folder:

• A profile's own folder: the session itself moves. It becomes that chat's active session, the chat gets a one-line summary, and you go on where you left off. Type /exit in the terminal, so the two don't split.
• A folder inside a profile's add_dirs, or any other folder: the session stays in the terminal. The chat of that profile, or of defaults.handoff for folders no profile reaches (a profile, or one chat such as whatsapp:<id> when that profile has several), starts a fresh session from a written brief and the project's path.

If that chat is in the middle of a turn, the turn goes on in the background. /status shows it, a permission it asks for is told to the chat and waits for you, and /resume takes it back.

---

WhatsApp

Add whatsapp: { auth_dir: ~/.angelia/wa } to the table and run angelia pair. It opens a local page with a QR code; on the phone that owns the number, choose Linked devices > Link a device and scan it.

Use a second, established number, not your personal one. Angelia ignores what its own account sends, so on your personal number it would not hear you, and it would answer as you. Its link can also read every chat on that account. And WhatsApp bans newly created numbers that start acting like robots, often within hours.

---

Security in one minute

An assistant that can read your files can be talked into reading them aloud. Read the security model before you give the bot to anyone but yourself.

• Only chats in the table reach the agent. In a group, only the owners are heard unless you name others.
• Only owners approve commands, change the session or restart. A group member's typed "yes" is refused.
• What the agent may do is its CLI's own permission mode. For a profile other people talk to, keep a cautious mode or set sandbox: true.
• Prompt injection is not solved: a web page or a forwarded message can still talk the agent into anything its permission mode allows.

Found a hole? Report it privately: SECURITY.md.

---

Backends

Each chat keeps one warm process, so a message never waits for a CLI to start. Permission prompts reach the chat on all four. Codex runs inside its own sandbox, which the operating system enforces: Angelia hands it the profile's rules, so it writes only in its folders and cannot read your credentials or the other profiles, shell commands included. pi has no sandbox of its own, so Angelia puts every pi shell command and every file read and write inside macOS's sandbox, made from the same rules. Every CLI plugs into the same small interface in src/brain/, and nothing else in Angelia knows which one is running.

---

Documentation

---

FAQ

What does it cost? Angelia is free and MIT-licensed. You pay only for your CLI's own subscription. Telegram bots and linked WhatsApp devices are free.

Does anything go through an Angelia server? No. There is no Angelia server, account, telemetry or update check. Each turn goes to your CLI's model provider under that CLI's terms. Telegram keeps bot messages on its servers; WhatsApp messages are end-to-end encrypted to the linked device.

Why not Remote Control or Claude Code channels? They are good at different things. See four ways to reach Claude Code from your phone, compared, including when not to use Angelia.

Does my computer have to stay on? Yes, the agent runs on it. A Mac mini or an always-on laptop is the usual home.

Can other people in a group use it? Yes, if you list them in allow_from. They can talk to the agent; they cannot approve its commands.

How do I update? angelia update installs the newest signed release and never touches your profiles. Then send /restart.

How do I remove it? Six commands, in the runbook.

---

Non-goals

Angelia is not an agent and will not become one. No second model, no skills system, no memory framework, no scheduler in the daemon, no plugin marketplace. Knowledge belongs in the profile's instruction file; scheduled work belongs to the operating system, which angelia jobs only sets up. No payments: the agent sends you a checkout link and you pay on your phone.

Next: an OpenCode backend. Linux with a systemd unit. /profile to switch which assistant answers a chat.

---

Contributing

Contributions are welcome. Read CONTRIBUTING.md first: it is short.

git clone https://github.com/korengast/angelia && cd angelia
npm ci --ignore-scripts && npm run build
npm test                                          # macOS with tmux: types, the suite, then a real pack and install
ANGELIA_STATE_DIR=$(mktemp -d) npm run dev -- init  # a scratch instance that never touches yours

• 🐛 Issues
• 🔐 Security reports, privately, never in an issue
• ✉️ info@useangelia.com for anything that is not a bug report

---

License

MIT — see LICENSE.

If Angelia is useful to you, a star helps other people find it.