Cadabra OS

An AI assistant for Windows that can see your screen and act on it, safely.

Press **Ctrl + ~** anywhere, or just say "Cadabra, …", and a frosted-glass panel opens next to your cursor. Ask about what's on screen, or tell it to do something: it points at things, clicks, types and scrolls in your real apps with a ghost cursor while you watch. Esc stops everything, instantly.

Warning

Public beta (0.9.14). Cadabra OS works day to day for its developers, but it's a beta: expect rough edges.

• Tested: Windows 11 x64; Claude with a Claude subscription (through Claude Code); voice, wake word and the natural voices; WhatsApp; Gmail with your own Google key; skills; announcements.
• Not tested yet (no accounts or hardware to try them): OpenAI Codex, Gemini, GitHub Copilot, Claude with an API key (only tested against a fake server so far), including web search, Claude via Bedrock or Vertex, Gmail app passwords, the Southern cloud voices, Windows 10, ARM64 PCs, non-US keyboards and input methods, and more. Help us test.
• The installer isn't code-signed yet. Windows SmartScreen shows "Windows protected your PC": choose More info → Run anyway. Only do this with the installer from this repository's Releases page.
• Found a bug? Open an issue and attach tray → Export diagnostics…. It's redacted, but read it before posting, and never paste API keys or tokens.

Download

Get the latest installer (CadabraOS-Setup-<version>.exe) from GitHub Releases. Each release lists the installer's SHA-256 checksum. To check your download, run Get-FileHash .\CadabraOS-Setup-<version>.exe in PowerShell and compare. Release notes: docs/RELEASE_NOTES_0.9.14-beta.md.

Features

• Summon anywhere. A keyboard shortcut you choose (default Ctrl + ~, or a mouse combination such as Ctrl + right-click) or a wake word. Start typing straight away: keystrokes during the opening animation land in the panel.
• Sees and acts. Reads the screen through Windows UI Automation and screenshots, highlights things with gold rings, and clicks, types, presses keys and scrolls with a visible ghost cursor. It handles multi-step tasks such as "open Google Maps and get me directions to the nearest pharmacy".
• Opens things. Any installed app or game ("open Spotify"), web pages, including spoken addresses ("open tv dot youtube dot com in Chrome"), and read-only diagnostics in a visible terminal ("do an nslookup for 8.8.8.8").
• Bring your own AI. Claude, OpenAI (Codex), Google Gemini or GitHub Copilot, through each vendor's official CLI or SDK, plus an offline Demo mode. Switch from the panel, the tray or by voice.
• Local voice. Wake word, speech recognition and natural voices run on your PC. Pick the assistant's name and voice, and the name becomes the wake word.
• Everyday helpers. The time, weather (Open-Meteo), "lock my PC", spoken greetings when you come back, read-only Gmail, and optional web search for news and sports.
• From your phone. Chat with your assistant on WhatsApp through WhatsApp's Agent Platform, with confirmation codes for anything risky.
• Safety first. A code-enforced safety gate decides what needs your OK, renders the confirmation itself from the real action, and blocks password managers and Windows security prompts. See Safety.

More in docs/screenshots. They show a synthetic demo desktop.

Requirements

• Windows 11 (x64).
• At least one AI account, or the offline Demo mode to look around:
  • Claude: Anthropic's Claude Code app (free to install; Cadabra can install it for you), plus either a Claude subscription or an Anthropic API key (Amazon Bedrock and Google Vertex AI also work). See Setting up Claude;
  • OpenAI: the Codex CLI (npm i -g @openai/codex) with a ChatGPT sign-in or an API key;
  • Google: the Gemini CLI (npm i -g @google/gemini-cli) with a Google sign-in or a Gemini API key;
  • GitHub Copilot: the Copilot CLI with your Copilot plan.
• For voice: a microphone, and about 450 MB of disk for the speech and voice models (downloaded on first use).

Install

1. Download CadabraOS-Setup-0.9.14.exe from the releases page, or build it yourself.
2. Run it. The installer isn't signed yet, so Windows SmartScreen warns: choose More info → Run anyway. It installs per user, with no admin prompt.
3. A short setup opens in the panel: try the shortcut, choose what to be called, connect your AI (with a live test), and optionally turn on voice. You can reopen it from the tray (Set up Cadabra…).

To uninstall, quit from the tray, uninstall from Windows Settings → Apps, and delete %APPDATA%\Cadabra OS.

Build from source

You need Node.js 24 (see .nvmrc), Rust stable (MSVC) and the Visual Studio C++ Build Tools.

npm ci
npm run build:native   # the Rust helper
npm start              # build the JS and run the app
npm run dist           # → dist/CadabraOS-Setup-0.9.14.exe (NSIS, per-user)

Handy dev modes: npm run demo (visual preview stage with every state), npm run demo:live (real windows, offline backend, no hooks) and npm run screenshots. CONTRIBUTING.md has the full command list, and docs/ARCHITECTURE.md explains how it fits together.

Setting up Claude

Cadabra talks to Claude through Claude Code, Anthropic's app. It's free to install; using Claude needs a Claude plan or an API key. Cadabra doesn't include it; you install it once and Cadabra uses it in the background. The setup screen (in onboarding, or Settings → AI accounts → Claude) walks you through three steps:

1. Get the Claude Code app. Press Install Claude Code. Cadabra shows you exactly what it will run (Anthropic's official installer), and installs it for your Windows account when you agree. No administrator rights are needed, and it takes about a minute. If that doesn't work on your PC, open Install it yourself instead: it explains how to paste one line into Windows PowerShell, with a Copy button and a link to Anthropic's install page. Then press Check again.
2. Connect your Claude account. Pick one:
   • Use my Claude subscription if you pay for Claude (Pro or Max). Press Sign in and finish the sign-in in the window Claude Code opens. There's no extra cost, but Anthropic's terms may restrict using a subscription through other apps, so this is at your own risk.
   • Use an Anthropic API key if you'd rather pay per use. Create a key at console.anthropic.com, paste it in and press Save key. Anthropic bills you for what you use, separately from any subscription. The key is stored encrypted on your PC and is only given to Claude Code, never to anything else.
3. Test it. Press Test. Cadabra sends Claude a tiny message and shows the answer ("It works!").

Web search with an API key: with an API key (or Bedrock / Vertex), the switch Web search with your Claude API key (in the Connect step and in Settings → Web access, on by default) lets Claude search and read the web for news and sports. Cadabra checks every search first, and Anthropic bills web searches per search, on top of normal use. Note that each web page Claude Code fetches also makes Claude Code send that page's domain (only the domain) to Anthropic for its own safety check. Turn it off and Claude simply can't search the web (weather still works).

Already have Claude Code installed somewhere unusual? Use Find it on my PC… under "Install it yourself instead".

Providers and accounts

Connect accounts in onboarding or Settings → AI accounts. Each card shows the status, the sign-in choices and a Test connection button.

Provider	Sign-in options
Claude	Always through your own Claude Code app: Use my Claude subscription (your Claude Code sign-in), an Anthropic API key (stored encrypted, given only to Claude Code), Amazon Bedrock or Google Vertex AI.
OpenAI	Sign in with ChatGPT (via Codex), using Codex's own login flow, or an OpenAI API key.
Gemini	Sign in with Google (via Gemini CLI), using the CLI's own login, a Gemini API key, or Vertex AI.
GitHub Copilot	Your own Copilot CLI sign-in (copilot → /login) or COPILOT_GITHUB_TOKEN.
Demo	Nothing; offline canned answers.

Every backend gets only Cadabra's tools: built-in shell, file and other tools are switched off, and each one runs with a private, empty configuration, so your own CLI settings, MCP servers and instructions aren't loaded.

Terms: please read. Cadabra only signs in through each vendor's own, unmodified CLI and login page. It never implements vendor OAuth itself, never reads or copies CLI credential files and never spoofs client identity. Even so, vendors' terms differ and change:

• Anthropic: Claude Code is Anthropic's software under Anthropic's terms; Cadabra doesn't bundle or redistribute it. Using your Claude subscription through Claude Code runs on your plan's limits. Anthropic's terms may restrict the use of subscriptions by third-party apps, so use this option at your own risk. An Anthropic API key (billed per use) is clearly permitted.
• OpenAI: signing in with ChatGPT through the Codex CLI uses your plan's Codex limits under OpenAI's terms. An API key is billed per use.
• Google: the Gemini CLI's own Google sign-in falls under Google's terms for the Gemini CLI. Google recommends an API key for third-party tools, which Cadabra also offers.
• GitHub: Copilot requests count against your Copilot plan.

You are responsible for complying with your providers' terms. Cadabra OS is not affiliated with or endorsed by Anthropic, OpenAI, Google, GitHub, Microsoft or Meta.

Privacy

• What leaves your PC: your requests, plus the screen content Cadabra needs to answer them, go to the AI provider you chose. With Claude, each web page it fetches also sends the page's domain (only the domain) to Anthropic for Claude Code's own safety check. Weather lookups send only the city name to Open-Meteo. Optional features send data only where you'd expect: web searches go through your AI, Gmail data comes from Google, WhatsApp messages go through Meta's agent service, and cloud voices send reply text to OpenAI.
• What stays local: the wake word, speech recognition and the natural voices. Cadabra's own windows are excluded from screenshots.
• Typing: Cadabra types with real keystrokes for every character on the target window's keyboard layout (Unicode only for the rest, such as emoji), so keyboard/mouse sharing tools like Input Director don't garble it. It reads the field back afterwards and tells you plainly if the text didn't come out right. Settings → Advanced → Typing method switches to Real keystrokes only or Unicode only. If an app reopens your unsaved tabs (Windows 11 Notepad does), Cadabra types in a new empty tab, and it asks before erasing any text it didn't type itself.
• Screen recordings and screen sharing: by default Cadabra's panel, ghost cursor, cards and pills are hidden from recordings, screenshots and shared screens (OBS, Xbox Game Bar, the Snipping Tool, Teams, Zoom), so a private chat never shows on a screen you share. Recording a demo? Turn on Show Cadabra in screen recordings and screen sharing (Settings → Privacy) or tick Presenting mode in the tray menu. It applies at once and stays on until you turn it off; a red ● Visible badge in the panel header reminds you. While it's on, anyone watching your recording or shared screen can read the panel, including your chat. Cadabra's own screenshots (for the AI, and the ones it sends to WhatsApp) still leave Cadabra out.
• The Cadabra project has no server. There is no telemetry, analytics or account.
• Secrets (API keys, tokens) are encrypted with Windows DPAPI. Logs (%APPDATA%\Cadabra OS\logs\) never contain typed text, email content, keys or tokens.
• Export diagnostics… in the tray creates a redacted bundle for bug reports. Review it before sharing it.
• Clear chat history: the 🗑 button in the panel, Settings → Privacy, the tray, or just say "clear my history" (also from WhatsApp). After you confirm, it removes your conversations from Cadabra on this PC (the panel and the WhatsApp conversation), ends the AI sessions so they start fresh, and deletes Cadabra's own session and temp files. It keeps your settings, skills, keys and WhatsApp pairing, and never touches your own Claude Code, Codex, Gemini or Copilot folders. GitHub Copilot keeps its sessions in your own ~/.copilot folder, which Cadabra doesn't clear. It can't remove copies elsewhere: the chat on your phone (delete it in WhatsApp; Meta keeps agent messages for up to 30 days) and whatever your AI provider keeps under its own policy (Anthropic, OpenAI, Google, GitHub).
• Keep chat history (Settings → Privacy): Until I clear it (default), Clear when Cadabra closes, or Clear after 1 hour of inactivity. With Until I clear it, startup only removes leftover temp files older than a day (terminal output, per-session hand-off files and screenshots), never your conversation history. Cadabra's deletions never follow links or junctions out of its own folders.

Safety and autonomy

Cadabra decides in code, not in the model, what needs your approval:

• Confirm cards show the exact command, keys, text or address and the target window, written by the safety gate from the real action. "Not now" is the default, and no answer means no.
• Always confirmed: commands or Enter in terminals and other command lines; sending, deleting, buying, paying and transferring; anything in banking, trading or checkout windows; sign-in buttons; addresses that came from the screen, the web or an email.
• Always blocked: password managers, Windows credential and UAC prompts, windows running as administrator.
• Esc (the physical key) stops typing within a keystroke or two, stops terminal commands and ends the run. Saying "stop" works too.
• Screen text, web pages, emails and messages are data, never instructions.
• Honesty check: Cadabra only says it did something if a tool that does that thing actually succeeded.

Choose how much it asks in Settings → Safety → When I act on your screen:

Level	What happens
Ask only for risky actions (default)	Ordinary clicks and typing just happen; the list above asks.
Ask before every action	Every action asks. Ordinary actions can be granted Always allow per app or site, and revoked any time.
Don't ask	No cards. Blocked targets stay blocked and Esc still works.

The full model, including the terminal allowlist and the web guard, is in docs/SECURITY.md.

Voice

• Say "Cadabra, …" (or your assistant's name). After an answer, you can follow up for a few seconds without the name. Say "thanks", "that's all" or "bye" to end; it also ends on its own.
• Push-to-talk: hold Ctrl + Win.
• Choose your assistant: Cadabra or one of the curated names (Vesper, Indigo, Octavia, Rosalind, Beatrix, Bramwell, Leopold, Lysander), or your own. The name is the wake word.
• Voices: natural British and American voices run locally (Kokoro). Optional "Southern" cloud voices use your own OpenAI key and are disclosed as AI-generated.
• Listen to samples in docs/voice-samples/.

Announcements

Say "Cadabra, make an announcement: dinner is ready" (or "announce that…"), or send "Announcement: dinner is ready" (or "Announce: …", or start with 📢) to your WhatsApp agent, and the PC says it out loud, word for word. The text never goes to the AI.

• It works while the PC is locked (it never touches the screen) and even when spoken replies are off. Without the natural voice installed, the Windows voice speaks.
• Settings → Announcements: a soft chime first (on by default), say it once to three times, louder playback, which speaker to play it on (for example a speaker system; this needs the natural voice), lower other apps' sound while announcing (on by default; restored afterwards, even after a crash), and whether to respect quiet hours (off by default: announcements are deliberate).
• If the PC's sound is muted, nothing is said and WhatsApp tells you so. Esc at the PC, or "stop" in WhatsApp, cuts it short.
• Only your paired WhatsApp chat can announce. Announcements are capped at 500 characters and 6 a minute, and Cadabra logs that one happened, never what it said.
• Your AI can announce too (for example from a skill: "remind everyone dinner is ready"). If you didn't ask for an announcement in that request, it shows you the text and asks first.

Skills: your own routines

A skill is a short note, in plain English, that teaches Cadabra how you like something done, like "my morning briefing" or "set up for work". Say one of its example phrases and Cadabra follows your steps, by voice, in the panel or from WhatsApp.

• Your skills live in Documents\Cadabra\Skills, created on first run with a README and a template. Updates and uninstalls never touch this folder.
• Built-in examples (morning-briefing, work-setup, quick-note) and the template ship in the install folder (resources\skills). Skills added there also load, but updates may remove them. If two skills share a name, yours wins.
• Make one: Settings → Skills → New skill from template (or say "create a new skill called plan my trip"), fill it in, save, and turn it on. New skills always start switched off.
• Safety: skills are instructions only. Nothing in a skill folder is ever run, and a skill can't change your autonomy level, permissions or safety checks.

The step-by-step guide, with tips and troubleshooting, is in docs/SKILLS.md.

Chat from your phone (WhatsApp)

This uses WhatsApp's own Agent Platform, where availability depends on your region and account: an agent you create in your WhatsApp account that only you can message.

1. Create the agent. In WhatsApp: Settings → Agents → Create an agent and give it a name. Open its chat → Chat info → API key and copy the key.
2. Connect Cadabra. Settings → WhatsApp: paste the key, Save, Test connection, then turn the switch on.
3. Pair. Cadabra shows a 6-digit code on the PC. Send it in the agent chat once. From then on, only that chat is accepted.

What to know:

• Risky actions ask in the chat with a one-time code ("Reply 4821 to …"). Send "stop" to stop, or press Esc at the PC. While a WhatsApp request is running, the PC shows it.
• Text, voice notes (transcribed on your PC) and pictures work. "Show me my screen" sends a compressed screenshot, only when you ask, and the upload is deleted from the service after sending.
• If the PC is locked, Cadabra says so and does nothing. It can't unlock it.
• Privacy: WhatsApp agent chats are not end-to-end encrypted. Meta's agent service processes them and keeps messages and media for up to 30 days, and your messages also go to your chosen AI.
• You are the agent provider. You run this agent yourself, so under WhatsApp's agent terms you are responsible for what it does. Use it only for your own PC and accounts.

Using Cadabra while you're away

• Display off is fine. If the screen has gone dark, Cadabra turns it back on for a WhatsApp request (one invisible, zero-distance mouse nudge) and keeps it on until the request is done. Turn this off in Settings → WhatsApp → Wake the display for WhatsApp requests.
• A locked PC stays locked. Cadabra never unlocks Windows, so it can't see or use a locked screen. WhatsApp tells you so; announcements still work.
• If you want remote control while you're away, Windows must stay unlocked. The relevant Windows settings are Settings → Accounts → Sign-in options → "If you've been away, when should Windows require you to sign in again?" (choose Never), the screen saver's "On resume, display logon screen" option, and Dynamic lock. The trade-off is real: anyone at your PC can use it while it's unlocked. Only do this somewhere you trust.
• Sleep: a PC that's asleep can't receive WhatsApp messages; nothing can wake it remotely. Either set Windows' sleep to Never (Settings → System → Power), or turn on Settings → WhatsApp → Keep this PC awake while remote access is on. That stops sleep while letting the display turn off, and uses more power.

Gmail (read-only)

Settings → Email offers two ways in:

• Secure (recommended): your own Google Cloud OAuth client (about 10 minutes, once) with gmail.readonly only. Disconnect revokes it.
• Simple: a personal-Gmail app password. This gives full mailbox access, but Cadabra only ever opens the mailbox read-only.

Then ask "did I get an email from Sam today?". Email is treated as untrusted: links are stripped, and after an email has been read, every action needs your OK.

Limitations

• Windows 11 only; there are no macOS or Linux builds.
• The installer is unsigned, so SmartScreen and some antivirus tools may warn.
• Apps with poor UI Automation support (some games, custom-drawn UIs) are harder to read and act in.
• Keyboard/mouse sharing tools (Input Director, Mouse Without Borders, Synergy, Deskflow, Barrier, Input Leap, ShareMouse) can send Cadabra's input to another PC. Cadabra detects them and tells you when input may not have arrived.
• Voice is English-only for now.
• Prompt injection can't be fully prevented. The safety gate's job is to make sure it can't lead to a risky action without your approval.
• The WhatsApp Agent Platform is a beta in limited regions.

Help us test

Cadabra connects to many services and runs on many kinds of PCs, and we can't try them all. If you have an account or a setup we don't, a short test helps a lot. docs/HELP_WANTED_TESTING.md lists what needs testing, with step-by-step instructions and what "good" looks like for each. Report results with the Test report issue template.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md (setup, testing rules, and the bar for changing the safety rules), and see docs/TESTING.md for the hands-on checklist. Please follow the Code of Conduct.

Found a security problem? Please report it privately: see SECURITY.md.

License

MIT © 2026 Cadabra OS contributors.

Cadabra OS uses third-party software and models under their own licences, listed in THIRD_PARTY_NOTICES.md. Both files ship with the installer. The research behind the design is in docs/research.md.