astar is a menu-bar voice assistant that can see your screen, act on your Mac, type for you, and run developer commands — all by voice. Ask what's on screen, tell it to do something ("open Safari," "add a meeting tomorrow at 3pm," "run git status"), and it executes and answers out loud — with a Spotlight-style HUD showing everything as it happens.
Runs on free APIs (Groq) + on-device models — no paid keys required. Screen reading is local-first: your screenshots are read on your Mac and never leave it unless the screen is image-heavy.
- See (local-first) — reads your screen's text on-device with Apple's Vision framework (Neural Engine); the image stays on your Mac. Only image-heavy screens fall back to a cloud vision model.
- Hear — local speech-to-text (
faster-whisper) with silence filtering, and hands-free auto-send: just stop talking and astar answers. - Act — a tool-calling agent controls your Mac by voice: open apps, add reminders, control Apple Music, read your calendar, create calendar events, take notes, and draft/reply to emails, and look things up.
- Develop — your voice sidekick for real work: types wherever your cursor is ("type my email address here") and runs terminal commands ("run git status") — astar is the terminal, no Terminal app involved.
- Speak — replies out loud; optionally with a natural AI voice (Cartesia) instead of the robotic macOS one. Stops when you quit or ask something new.
- Show — a Spotlight-style HUD floats up while you talk: a live mic level (you can see it hearing you), your transcribed words, a thinking state, and the answer as on-screen text while it's spoken.
- Remember — astar keeps real conversation memory (follow-ups like "do that again" just work), plus a chat-style History window with your whole log (menu → History).
- Never down — every provider key you add joins an auto-fallback chain (Groq → Cerebras → NVIDIA → Mistral → OpenRouter). Rate-limited or down? The next brain answers.
- Settings in-app — paste your API keys into a native Settings window (menu → Settings). No file editing; a fresh install walks you through it.
| You say | astar does |
|---|---|
| "What's on my screen?" | Reads it on-device and tells you |
| "Open Safari" / "Play my music" | Opens the app / controls Music |
| "Add a meeting tomorrow at 3pm" | Creates a Calendar event |
| "Make a note to buy groceries" | Saves a note in Notes |
| "Email John saying I'll be late" | Drafts the email in Mail (you send it) |
| "Text mom I'm on my way" | Reads it back, sends only after you say yes |
| "Type my email address here" | Types into whatever field your cursor is in |
| "Run git status in my project" | Runs it and speaks the result |
| "Fix the grammar of what I copied" | Rewrites your clipboard, ready to paste |
| "Summarize my clipboard" | Reads what you copied, speaks a summary |
| "Open YouTube" / "Search Google for X" | Opens the browser right there |
| "Set a pomodoro timer for 25 minutes" | Announces out loud when time's up |
| "What's the tallest mountain?" | Looks it up and answers |
Safety: anything that sends (email) is always drafted for you to review — astar never sends on its own. Destructive shell actions (deleting, overwriting, installing) require your explicit confirmation first, and sudo is blocked entirely.
Grab Astar.dmg from Releases, open it, drag astar into Applications, and launch. The app is fully self-contained — no Python, no setup, no Terminal.
Two things on first run:
- astar opens Settings automatically — paste your free Groq key and hit Save. Done.
- Grant the permission prompts (Microphone, Screen Recording, Accessibility, and Automation for Calendar/Notes/Mail) — one time.
Optional extra keys (all free) go in the same Settings window and become automatic fallbacks: Cerebras (same model as Groq), NVIDIA NIM, Mistral, OpenRouter.
ASTAR_TTS=cartesia # natural AI voice (free key at cartesia.ai)
CARTESIA_API_KEY=sk_car_...
ASTAR_STT=deepgram # sharper transcription (free $200 credit at deepgram.com)
DEEPGRAM_API_KEY=...The free local stack (say + faster-whisper) stays the default and the automatic fallback — these upgrades never break offline use.
Click the ✦ in your menu bar (or press ⌃⌥Space) → talk → just stop talking. The hotkey is Control+Option+Space because nothing else on macOS responds to it.
| Layer | Tech | Where it runs |
|---|---|---|
| Speech-to-text | faster-whisper (base.en) + VAD + silence auto-send; optional Deepgram nova-3 |
on-device (cloud opt-in) |
| Screen text | Apple Vision framework OCR | on-device (Neural Engine) |
| Screen reasoning | Groq llama-3.3-70b (text) / llama-4-scout (vision fallback) |
cloud (free tier) |
| Agent (tool calling, 19 tools) | LangGraph ReAct + gpt-oss-120b, auto-fallback across 5 providers |
cloud (free tiers) |
| Actions | AppleScript + shell (apps, Calendar, Notes, Mail, typing, terminal) | on-device |
| Text-to-speech | macOS say; optional Cartesia sonic-2 natural voice |
on-device (cloud opt-in) |
| UI | menu bar (rumps + SF Symbols), color-coded HUD, History + Settings windows (AppKit) |
on-device |
Local-first screen reading (three-tier):
- On-device — Apple Vision OCR reads the screen text locally; the image never leaves the Mac.
- Cloud text — a Groq text model answers from the extracted text (no image uploaded).
- Cloud vision — only visual questions ("what's in this photo?") or image-heavy screens send the screenshot.
python3 -m venv venv
venv/bin/pip install -r requirements.txt
cp .env.example .env # add your free Groq API key
venv/bin/python astar_menubar.pyThe packaged app reads config from ~/.astar/.env instead (mkdir -p ~/.astar && cp .env ~/.astar/.env), so it runs with no project folder at all.
venv/bin/python setup.py py2app
install_name_tool -change '@executable_path/../../../../Python3' \
'@executable_path/../Frameworks/Python3.framework/Versions/3.9/Python3' \
dist/astar.app/Contents/MacOS/python
codesign --force --deep --sign "Apple Development: aryangupts05@gmail.com (KKJ2N9P2ZS)" --identifier com.astar.astar dist/astar.app
hdiutil create -volname Astar -srcfolder dist/astar.app -ov -format UDZO Astar.dmgProduces a fully self-contained astar.app (~290 MB) — Python and every dependency frozen inside. Signing with the Apple Development certificate anchors the app's identity to the cert — permissions survive rebuilds.
- ✅ Phase 1 — see + speak (screenshot → vision → voice answer)
- ✅ Phase 2 — act (voice commands trigger real Mac actions via tools)
- ✅ Phase 3 — native-app reach (Calendar, Notes, Mail) with no OAuth
- ✅ Phase 4 — local-first screen reading (on-device OCR, cloud only when needed)
- ✅ Phase 5 — Spotlight-style HUD overlay (live mic level, transcript, thinking state, on-screen answers)
- ✅ Phase 6 — hands-free flow + native polish (auto-send on silence, SF Symbol menu, ⌃⌥Space)
- ✅ Phase 7 — fully standalone app (no venv, no project folder, no Terminal)
- ✅ Phase 8 — developer sidekick (voice terminal + type-anywhere), conversation History, DMG pre-release
- ✅ Phase 9 — multi-provider auto-fallback (5 free brains), in-app Settings for keys, natural voice (Cartesia), sharper hearing (Deepgram), color-coded HUD states
- ✅ Phase 10 — full Settings panel (keys, voice, hearing, MCP, offline brain), branded onboarding window, iMessage with a hard confirm-before-send gate, offline mode via Ollama (
OLLAMA_MODELjoins the fallback chain), Gmail/Notion/anything via the MCP servers field - Next — menu-bar waveform while speaking; wake word ("hey astar"); iOS companion.
Contributions are welcome — see CONTRIBUTING.md for setup, project layout, and good places to start. The roadmap items above are up for grabs; open an issue to claim one.