SaarthurR/atticus-mac

Hold ⌃ control ⌥ option space, say what you need, let go.
Atticus moves your windows, finds your files, reads your screen and gets it done.

☕ Leave a tip · Atticus is free; tips keep it going.

🧠 Learns as you use it  ·  ⚡ Fast  ·  🔑 No API key  ·  Free and open source

curl -fsSL https://raw.githubusercontent.com/SaarthurR/atticus-mac/main/install.sh | bash

Needs macOS 26 and an AI client: Claude Code on a Claude plan, Devin, Pi or a local model. Full install steps

• Learns. Ask for something new once and it works out the steps. Ask again and it runs in a blink, with no AI.
• Instant commands. Opens apps, moves windows, plays music and searches the web with no AI at all.
• Sees your screen. Ask about anything on screen. Ask "where do I click?" and it points at the spot.
• Draws to explain. "Explain this and draw it" builds a labeled diagram on your screen.
• Dictate anywhere. Hold fn, talk, let go. Your words land in any text field, cleaned up.
• Background agents. Big jobs run behind your apps while you keep working.
• Meeting Copilot. Answers and notes during calls, saved on your Mac.
• Remembers you. Say "remember…" and every ask after that knows it.
• Your plan, no API key. Runs on Claude, Devin, Pi or a local model.
• Private and safe. Your voice stays on your Mac. Deletes, sends and purchases ask first.

On Windows? @FindlayHi built Atticus for Windows, with integrations for Home Assistant, Jellyfin, Immich and more.

Safe mode runs the AI's commands in Claude Code's sandbox, so they can only write to a scratch folder. Before anything deletes, sends, buys or changes a file, Atticus asks you first. rm, sudo, disk tools and shutdown are always blocked. Every exact command is in the ask log. Apple's on-device speech turns your voice into text, and audio never leaves your Mac.

Hold fn to talk. Double-tap to lock. In any text field, hold the fn (🌐) key, speak, then let go. Double-tap it to lock dictation on for hands-free talking; an orange ring circles the pill, and one more press inserts. fn is the shortcut until you record another in Settings → Dictation (a key combo, an F-key, or a modifier chord like fn+Control); a shortcut you already set stays. If macOS's "Press 🌐 key to" setting opens emoji, switches input source or starts Apple dictation, Settings and setup show "Set Press 🌐 key to Do Nothing" with a button to Keyboard settings. fn with another key (fn+Delete, fn+←) stays that key's shortcut. While you talk, a small pill shows a sound wave. The Dictation tab shows your words today and all time, time saved, sessions, your dictionary and history. Verbatim types Apple's on-device transcript with no AI. Clean up makes one quick AI pass that keeps your words, fixes words it clearly misheard ("talk it and it' type" becomes "talk to it and it'll type"), and drops the slips: "um" and "you know" go, "scratch that" removes the thought before it, "four, actually five" leaves five, a spoken list becomes a list, and "new line" or "question mark" become formatting. It types what you dictate and never answers or acts on it. To spell names and terms it uses your Dictionary and the text just before your cursor. It starts while you talk, so the text lands soon after you let go; if the AI's version adds or drops too much, Atticus types your words with only the obvious fillers removed. Highlight text first and Clean up tidies that text in place. Esc cancels. When the words land, the pill turns into a green check and fades. With no text field selected, it says "Nothing selected to insert — saved to History." Dictation never leaves your words on the clipboard: if a field only takes a paste, Atticus borrows the clipboard for that one paste and puts back what you had copied. If the field changes or Atticus can't confirm the words landed, it saves them to Dictation History and says "Saved to History" instead of typing twice; with History off, the words stay in the pill.

This is how you show Atticus something; Draw on screen is how Atticus shows you. Click the pointer button, Point at your screen, next to the mic in the ask box. The cursor becomes a crosshair and the box says "Click, circle or scribble on anything, then ask". Mark the spot, then type or say your question and send. Another stroke near the mark replaces it; move away and your clicks reach your apps again, with the mark still showing. Atticus's own box and cards always take their clicks, so you can type while pointing. Click the pointer button again to stop or to mark somewhere else. A small picture of what you marked waits in the box; its × removes it, and Esc clears everything. Atticus gets a crop of that spot with your question, and the mark stays until you send. While a mark is waiting, instant commands and early thinking wait too.

Ask where to click or how to do something and Atticus shows you instead of only telling you: it draws boxes, circles, arrows and labels over your screen, with a pointer that moves to each spot. It goes one step at a time and moves on when you click the highlighted spot, change that value, or say "next".

Ask it to explain something and draw it ("explain the Pythagorean theorem and draw it on my screen") and the drawing builds up like a whiteboard: each step adds to the last, and a card in the opposite corner keeps every caption so far. It moves through the steps by itself. It works from what you have open: with a video, page or problem on screen, it marks up that figure and uses its numbers, unless you ask for a fresh example. Drawings go on the screen where you asked (the one with the Atticus box) unless you name another. Worked examples and practice problems are written line by line in large text on one panel, readable from your chair on a laptop or a monitor.

The drawing stays while you keep asking about it, and Atticus can add to it; it changes only when an answer draws something new. Click any mark (a box, an arrow, a label, a line of text) to select it, then ask "how does this work?": like Point at your screen, the question carries that mark and a picture of it. While a drawing is up, the Atticus box moves out of its way and comes back when it's gone. Close the card or press Esc to clear it. Steps are spoken only when Read answers aloud is on. The drawings never take focus, and clicks pass through everywhere except on a mark. Turn it off in Settings → General → Draw on screen to show you.

In Settings → Intelligence, choose Cheapest, Balanced (the default) or Most capable. Cheapest keeps every ask, meeting question and new agent on Haiku. Balanced keeps questions and quick commands on Haiku and gives real work to your work model; if a task turns multi-step, fails, or ends without a confirmed result, it continues once on the work model. Most capable uses the work model for every AI ask and agent. Instant commands skip the AI in every mode. Work model picks Sonnet or Opus; Opus is stronger and uses more of your plan.

With a custom server connected, Atticus uses that server's model. Under Custom server, choose an Agent model from its model list, or leave it empty to use the main model. Running agents keep their current model.

Atticus can send Claude Code to a local server that implements the Anthropic Messages API. Claude Code must be installed, but you do not need a Claude account.

1. Start a server and load a model:

   Server	Version with /v1/messages	Default address
   Ollama	0.14.0+	http://localhost:11434
   LM Studio	0.4.1+	http://localhost:1234
   llama.cpp llama-server	builds after Nov 28, 2025	http://localhost:8080
   vLLM	0.11.1+	http://localhost:8000

   Ollama starts with ollama serve; LM Studio uses lms server start --port 1234; llama.cpp uses llama-server -m /path/to/model.gguf; vLLM uses vllm serve <model>.

2. Open setup → Change provider → Custom server, or Settings → Intelligence → Custom server. If a server is on a default port, Atticus offers Use Ollama, Use LM Studio, Use llama.cpp, or Use vLLM.

3. Leave Key empty for an unauthenticated local server. Pick a model from the list Atticus reads from GET /v1/models, then ask normally.

Small local models are usually weaker at reliable tool use and following long screen context. Screen reading also needs a vision-capable model; text-only models can still use accessible window and page text.

Ask for something big ("find me USB-C hubs") and Atticus hands it to a background agent. A chip shows up in the corner while you keep working. The box, the dictation pill, the chips and the done card show up on the display your mouse is on. Hover it to see the live steps and a mini screen of the work. To change course, just talk: "tell the hub agent to check HDMI too" steers the running agent instead of starting a new one. When it finishes, a card shows the result once you stop typing. During a meeting or screen share, you get a quiet notification instead. If an agent needs a permission or a connector, it asks on its chip, then carries on. Turn on agents and their connectors in Settings → Agents (or the setup step).

A long ask in the box moves to an agent by itself, with no card, and agents Atticus offers start right away. To move one sooner, press ⌃⌥↩ from any app while it runs.

Agents work behind you. Their clicks, typing, scrolling and keys go straight to the app they work in, so your pointer, your front app, your windows and your Space stay where they are. Web work happens in the agent's own browser window, in your signed-in profile; your tabs are left alone, and the window closes when the task ends. If an agent's process stops mid-task, Atticus restarts it once and it picks up where it was. When an agent asks to do something, Always allow for this task approves that same kind of action until the task ends; the next task asks again.

Say “make an agent called Researcher that finds sources and writes a short brief” to save reusable instructions, then “ask Researcher to…” to start it. Saved agents can include a folder or files and can be listed, renamed, or deleted by voice or in the Agents view.

Background agents currently require Claude Code. Pi and Devin handle foreground asks; their meeting transcripts and recaps stay local. Pi has no built-in sandbox, so Atticus disables its direct file-edit and MCP tools and Safe mode asks before every shell command; its read tools still have your account’s file access.

Plain questions and answers can be saved in the Agents window: switch to Chats at the top. Chats keep only answers, never actions or agent tasks, stay on your Mac, can be renamed, and are never sent back to the AI. Turn saving off in Settings → Memory → Learning → Save chats.

Enable Meeting Copilot in Settings → Meetings → Meeting Copilot settings, then open it for a call or try the demo. Drag its header or empty background in any state; the minimized pill also drags. Positions and expanded sizes are remembered per display. Double-click the header to return to the default spot. Frames stay inside the display’s usable area, including after a display change.

Save meeting transcripts is on by default. While listening, a quiet indicator shows when saving is active. Text, speaker labels, timestamps, notes and copilot answers save incrementally under $ATTICUS_DIR/meetings/<meeting-id>/ (normally ~/.config/atticus/meetings/). Each folder is private (0700), with metadata.json and an append-only events.jsonl (0600). Unfinished speech is checkpointed every two seconds; interrupted calls remain readable. Audio is never saved.

Settings → Meetings, or See all meetings after a call, opens the local archive. Search titles and transcripts, use ↑/↓ and Return to browse, ⌘F to search and Esc to go back. Each meeting shows its recap, action items, notes, answers and timestamped transcript. Copy, export Markdown, or delete with confirmation. Turning saving off stops the current archive and asks whether to keep or delete past meetings.

With AI meeting summaries on (the default), Claude reads the transcript once after each ended session and writes a summary and action items, on your own Claude plan. Turn it off to keep transcripts entirely on your Mac; you still get a simpler local recap that quotes decisions and opening/closing speech. A failed AI recap leaves the local transcript intact. Resuming cancels a pending recap and the next End summarizes the full transcript. Closing or pausing stops recap work; already saved text stays on your Mac. Asking Atticus about a past meeting lets it search that archive with --meeting-history "<keywords, weekday or YYYY-MM-DD>". Live question answering retains the selected Meeting Copilot answer policy.

Choose Report Feedback… in the menu bar, Report feedback in Settings, or say/type “report feedback” or “report a bug”. Review the exact text before opening a GitHub issue draft. It contains a short template, version/commit, macOS and Mac model, model, safe mode and input settings. Include my last ask starts off; answers, screen content and command logs are never attached. Submit the draft yourself on GitHub.

You need:

• macOS 26 or later (Atticus uses Apple's new on-device speech)
• An AI client: a paid Claude plan (Pro or Max) and Claude Code, the Devin CLI signed in to a Devin plan, Pi with your chosen provider/model, or a custom server through Claude Code with no Claude account. Pick one in setup (“Change provider”) or Settings → Intelligence.
• Apple's command line tools: xcode-select --install
• Accessibility permission enables native clicks, scrolling, menus, keys, dragging and field typing.

Paste this in Terminal:

curl -fsSL https://raw.githubusercontent.com/SaarthurR/atticus-mac/main/install.sh | bash

It checks your Mac, downloads Atticus to ~/.atticus, builds ~/Applications/Atticus.app, and opens it. Atticus starts at login and updates itself from there (turn that off in Settings → About & Updates).

On macOS with Nix flakes enabled:

nix run github:SaarthurR/atticus-mac

The flake installs its packaged Atticus version, so macOS 26+ and Apple's command line tools are still required. Run that command again to update. nix profile add github:SaarthurR/atticus-mac installs an atticus launcher; update it with nix profile upgrade atticus, then run atticus. Nix installations show this update path in Settings instead of using Atticus's Git updater.

Working on the code instead? Clone the repo anywhere and run ./build.sh after each change. A Devbox environment is included for Python regression tests; run devbox shell, then devbox run test.

The first launch opens a setup window. It checks your AI plan, then asks for each macOS permission. After that, Atticus lives in the menu bar. Open it from Spotlight (⌘Space, "Atticus") for Settings: shortcut, voice, model, privacy, memory and usage. Settings and setup follow your Mac's light or dark appearance. If you sign out of your AI client later, the setup window comes back by itself. To see it again: defaults delete com.atticus.app onboarded, then restart the app.

Test: python3 atticus.py --selftest on macOS, plus python3 -m unittest discover -s tests -v for offline regressions. After building, ~/Applications/Atticus.app/Contents/MacOS/Atticus --selftest checks native transcript matching without opening the app. Node, when installed, also checks embedded JavaScript syntax. For the UI interaction checks, run python3 -m http.server 8765 --bind 127.0.0.1 from the repo and open http://127.0.0.1:8765/tests/ui.html; it uses a mock native bridge and makes no Mac actions or AI calls.

Remove: launchctl bootout gui/$(id -u)/com.atticus.app, then delete ~/Applications/Atticus.app, ~/.atticus, ~/.config/atticus (your settings and history) and ~/Library/LaunchAgents/com.atticus.app.plist.

Say "tell me when Codex is done" or "watch this page until it says shipped". Atticus sets it up once, then checks every 5 seconds on your Mac with no AI, so waiting is free. When it fires you get a notification, and it runs a follow-up if you asked for one. A window must stay open on this desktop (covered is fine). Coding agents like Codex are watched through their own log, with no screen at all. Say "stop watching" to cancel.

Say "every weekday at 8, summarize my calendar" or "every 30 minutes, check my inbox". Atticus saves a routine and macOS wakes it on time, so it costs nothing while it waits. Each run starts a background agent on Cheapest unless you chose another mode, and you get a notification with the result. Runs are skipped while Atticus is paused, and a restart never repeats one. See and remove routines in Settings → General → Scheduled routines, or ask Atticus to remove one. Like other agents, routines need Claude Code.

Atticus has to stay fast and nearly free, so new features must fit under these limits:

• Instant commands: no AI, $0.
• AI asks: median under $0.002 and 6 s over the last 50 (Oct 10, 2026: $0.00095, 5.0 s). Check with python3 atticus.py --budget.
• System prompt: under 10,000 characters in source and at most 10,050 with the installed helper path. Every ask pays for it, and tests enforce both limits.
• Anything that waits or runs in the background: $0 while it waits. AI only to set it up and to act at the end.

Atticus sends a random ID (made on your Mac, not tied to you) with daily use, ask outcomes, feature names, timings, dictation outcomes, and code locations for errors. It never sends task text, dictated words, file contents, paths, or screen content. Turn it off in Settings → Account & Access → Count me as a user.

If you say yes to Help improve Atticus (asked once, off until you do), a task that fails sends what you asked, the steps Atticus took and why it failed, under the same random ID. Emails, numbers, file paths, link details and anything typed for you are removed on your Mac first. Turn it off in Settings → Account & Access → Help improve Atticus.

• Atticus.swift: the app (hotkey, speech, overlay, onboarding window)
• atticus.py: the brain (fast commands, system prompt, helpers for windows, web and screen)
• ui/ui.html, ui/onboarding.html, ui/settings.html: the overlay, the welcome flow, and Settings
• ui/AppIcon.icns: the app icon
• ui/orbs.js: the thinking-orbs engine (MIT, Jakub Antalik)

MIT. See LICENSE. ui/orbs.js is from thinking-orbs, also MIT.

Run regressions with a scratch ATTICUS_DIR and use tests/ui.html and tests/settings.html for mock-bridge UI checks. Keep personal agent settings, credentials and runtime state out of commits. Anonymous usage telemetry uses a public PostHog capture token. Set ATTICUS_POSTHOG_KEY to override it (an empty value disables telemetry), or turn off Count me as a user in Settings.

Hands: ideas and some logic adapted from Plip (github.com/hussainn7/plip-oss, MIT). Background key authentication and menu-shortcut presses follow Cua Driver (github.com/trycua/cua, MIT).