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, or xAI, and 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.
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.

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

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

Keys are stored in the macOS Keychain as "Twin <provider> API key", never in a file on disk.

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. 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.

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.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.