docs

install

Two ways onto your Mac: a one-line install script, or the .dmg by hand. Either way you end up with Twin.app in Applications.

quick install

Downloads the latest release's .dmg, mounts it, copies Twin.app into /Applications, and clears the quarantine flag so Gatekeeper doesn't block the first launch. Safe to re-run: an existing install gets replaced, not skipped.

manual download

Not keen on piping a script into bash? Grab the .dmg from the download section on the landing page instead, and drag Twin.app into Applications yourself.

the gatekeeper warning

Twin ships ad-hoc signed, not notarized by Apple. On a Mac other than the one that built it, the first launch after a manual download gets blocked: "Twin can't be opened because Apple cannot check it for malicious software." Click Done, then:

1. Open System Settings → Privacy & Security.
2. Scroll to the Security section. You'll see "Twin was blocked to protect your Mac" with an Open Anyway button next to it.
3. Click Open Anyway, then confirm Open (Touch ID or your password may be asked for).

Or skip all of it: xattr -cr /Applications/Twin.app in Terminal after dragging Twin in. The quick install script does this step for you automatically.

building from source

git clone https://github.com/woustachemax/twin.git
cd twin
python3 -m venv .venv
source .venv/bin/activate
pip install anthropic duckdb python-dotenv pynput pyobjc-framework-Cocoa pyobjc-framework-Quartz pyobjc-framework-Vision pyobjc-framework-EventKit pyobjc-framework-Speech pyobjc-framework-AVFoundation
python3 buddy.py

That's the core install. You'll need Python 3 with Tk (the python.org installer includes it, or brew install python-tk). Add pip install pypdfium2 torch transformers sentencepiece protobuf Pillow if you also want /ingest. It pulls in torch, so it's a much bigger download, and it's why the downloadable app leaves it out entirely.

first run

The first time Twin starts, or any time ~/.twin/config.json is missing or setup wasn't finished, it opens a setup window before the chat widget. Four steps and a summary:

1. Provider. Pick Anthropic, OpenAI, Google Gemini, xAI, or Ollama. For a cloud provider, paste your API key: Twin checks it with one small test request, then saves it to your macOS Keychain. Wrong key, out of credits, or the wrong provider: it says so and lets you try again. For Ollama, there's no key: see running locally with Ollama for what happens instead.
2. Name. What Twin should call you. Filled in with the first name from your Mac account.
3. Buddy. Pick one of the five personas. Twin is selected by default.
4. Permissions. Buttons for Calendar, the hotkey, and Messages. macOS only prompts when you click one. This page can be skipped.
5. Done. A summary of your choices. Twin creates your database at ~/.twin/twin.duckdb here.

Your API key is not saved in a file. It goes straight into the macOS Keychain. Close the setup window before finishing and Twin quits; it picks up at step 1 next time, with your provider and key filled back in.

running locally with ollama

Ollama is a fifth provider choice, and the local one: pick it in setup and the model runs on your Mac, with no API key and nothing to sign up for.

installing ollama

Twin looks for either the Ollama.app download in /Applications, or the ollama binary from a Homebrew install (brew install ollama), checking /usr/local/bin and /opt/homebrew/bin directly so it's found even when Twin is launched from Finder, which doesn't inherit your shell's PATH. Install either one before picking Ollama in setup.

picking it in setup

Select Ollama on the provider step. If it isn't already running, Twin starts it itself, either by opening the app or by launching ollama serve from the binary, and waits a few seconds for it to answer before moving on. Twin does the same automatic start on every later launch whenever Ollama is your saved provider, not just during setup.

If you have no models pulled yet, Twin recommends one sized to how much RAM your Mac has, shows its approximate size, and downloads it when you click Download. That download needs an internet connection; after it finishes, chat with that model runs fully on your Mac. Replies stream in as the model generates them, the same as typing to a cloud provider.

using a model you already have

If you've already pulled models with Ollama, the setup window lists them as chips, click one to use it. You can also type the exact name of any model you've pulled yourself into the field. Twin only auto-downloads the one model it recommends; typing the name of a model that isn't pulled yet tells you to run ollama pull <model> in a terminal first.

cancelling a download, and running out of space

While a model downloads, a Cancel link sits next to the progress bar. Before starting, Twin also checks that your disk has enough free space for the model plus a small margin, and tells you the exact numbers instead of starting a download that can't finish. If space runs out mid-download instead, Ollama reports the problem and Twin shows the same "not enough free disk space" message.

what stays on your mac

There's no key to store for Ollama: nothing gets saved to the Keychain for it. The model itself lives wherever Ollama keeps its own models, outside ~/.twin. Twin's config.json still records that you picked Ollama and which model, same as it would for any other provider.

Conversation summaries work the same way regardless of provider, but matter most here: ask something like "summarize my messages with Alex" and Twin asks once before turning this on at all. Once on, each request reads only the one named, one-to-one thread straight from Messages (group chats aren't included), up to the last 60 messages, and sends it to whichever provider you picked to write the summary. With Ollama, that never leaves your Mac. Either way, nothing from that thread is written to twin.duckdb or anywhere else on disk; it's read fresh every time you ask. This needs the same Full Disk Access as the rest of Messages reading.

what still needs the internet

Chat with Ollama runs fully on your Mac once a model is downloaded. A few other things don't go through your chosen provider at all, and still reach out regardless of whether you're on Ollama or a cloud provider: looking up an SEC filing talks to SEC EDGAR, flight search talks to its own flight data provider, and /ingest's first run downloads the Donut OCR checkpoint from Hugging Face. All three need internet the same way they would with any provider.

permissions

Grant these from the setup window's permissions page, or later in System Settings. macOS applies a permission change on relaunch, not immediately. Quit and reopen Twin after granting one for it to take effect.

Twin keeps working without any of these. It says in the widget which feature is off and where to turn it on.

commands & hotkeys

Everything Twin responds to, typed or held.

personas

Pick one during setup, or switch anytime with /persona <key>. Commands take the key, not the display name.

Luna is the only one that resizes: drag the grip in its bottom-right corner, anywhere between 360×350 and 640×720. It opens at 420×460 and remembers the size you leave it at until you quit. Every other persona stays a fixed 360×350 widget with no grip.

providers

Five supported providers, one client each behind a common interface. Switch anytime with /setup.

Keys for the four cloud providers are stored in the macOS Keychain as "Twin <provider> API key", never in a file on disk. Ollama has no key to store.

your data

Everything Twin keeps lives in ~/.twin/, outside the repo:

• ~/.twin/twin.duckdb: parsed transactions, the full raw SMS text, and anything loaded with /ingest.
• ~/.twin/config.json: your name, persona, provider, and setup state.

Your API key sits separately, in the macOS Keychain, for the four cloud providers; Ollama has no key to store. There are no accounts, no sync, no analytics, and no Twin server. Everyone who installs Twin gets their own database, created in their own home folder.

Every insert into twin.duckdb also writes a row to its access_log table, recording what was read, when, and by which part of Twin.

Conversation summaries ("summarize my messages with NAME") are the one exception that never touches this database: they're opt-in, and each one reads a single one-to-one Messages thread fresh at the time you ask, then sends it to your provider to write the summary. Nothing from that thread is written to twin.duckdb, config.json, or anywhere else on disk. See running locally with Ollama for the full behavior.

reset to a clean state

Delete ~/.twin and Twin runs setup again on next launch, as if freshly installed:

uninstall

1. Quit Twin, then drag Twin.app out of Applications.
2. Delete ~/.twin (your database and config).
3. Remove the Keychain entry for whichever provider you used. For Anthropic, that's service "Twin Anthropic API key", account "twin":

faq

troubleshooting

limitations

• macOS only.
• The SMS parser targets Indian bank and UPI message formats. Other formats are ignored until someone adds patterns for them.
• The pipeline reads only the 200 most recent messages per run.
• Twin only looks at the five most recent transactions when chatting.
• Each chat message is answered on its own. Twin doesn't remember earlier turns.
• Answers about your screen are vague on purpose, since only a one-sentence summary is sent.
• One ingested document is active at a time. Loading a new one with /ingest replaces it; older ones stay stored but out of the conversation until re-ingested.
• Filing lookup only searches EDGAR's "recent" filings window, roughly the last year. An older filing of that type comes back as not found even if it exists.
• Donut is fine-tuned on receipts, so extraction quality on other kinds of document photos is weaker.
• Twin only auto-downloads the one model it recommends. A different model has to be pulled yourself with ollama pull <model> first.
• SEC filing lookup, flight search, and /ingest's one-time OCR model download all need internet, regardless of whether you picked Ollama or a cloud provider.
• Twin.app ships ad-hoc signed, not signed with a paid Developer ID or notarized. That's a deliberate call for a portfolio project, not a gap to fill later.

Still stuck? Open an issue on GitHub.