install

get your twin running

Download the macOS desktop build, then choose your Obsidian or Markdown vault and quick-notes folder during onboarding. Node 20+ is only needed for source development and source-only MCP wiring.

Latest public DMG: v0.9.5. A v1.0.0 release has not been published yet.

For most people

You only need the desktop app and an Obsidian or Markdown folder.

  1. 01

    Download

    Get the newest macOS .dmg from GitHub Releases.

  2. 02

    Open

    Drag Twin to Applications. If macOS warns you, right-click the app and choose Open.

  3. 03

    Pick a vault

    Onboarding asks for your Obsidian or Markdown vault and the folder where /inbox should create titled quick notes.

download latest release →

Optional: source MCP wiring

Use this only from a checked-out repo when you want Claude Desktop to poll the same local action queue.

Source CLI setup

This is not an npm install path. Build the repo, then run the generated CLI directly. Use --quick-notes-path to match your vault’s inbox folder.

$ node packages/cli/dist/bin.js init --quick-notes-path "📥 Inbox"

The public desktop release does not depend on npm registry packages.

$ node packages/cli/dist/bin.js action approve <id>

Desktop handoffs start as needs_approval. Approve in the app or Terminal for that request only; Twin does not save trusted desktop capabilities.

Develop from source

For contributors: the desktop app is Tauri + Rust + Vite, and the landing page is Astro.

$ git clone https://github.com/rzrizaldy/twin_md

clone the monorepo

$ npm ci

install workspace dependencies

$ npm run build

build core, MCP, and CLI

$ npm run dev:desktop

Tauri dev — floating pet + chat panel

Optional provider keys

Regular chat in the app is local-first when Claude Code or Codex is installed (Twin injects the bundled twin MCP). Add Anthropic, OpenAI, or Gemini keys only if you want custom sprites, generated chat backgrounds, or API-based chat without the CLI.

Recommended model: claude-haiku-4-5 — flash-equivalent, cheap, warm.

export ANTHROPIC_API_KEY=sk-ant-…
get key at console.anthropic.com →

If something feels wrong

Start here before digging through internal files.

Developer smoke test:

$ npm run build:web -w @twin-md/desktop
troubleshooting

desktop app won’t start

Build from apps/desktop with npm run dev:desktop (Vite must be on port 1420 in dev) or install a release bundle. Check the terminal for a Rust or webview error.

source CLI command not found

Run npm run build from the repo root, then use node packages/cli/dist/bin.js.

pet shows blank / default state

Use the tray harvest action, or from source run node packages/cli/dist/bin.js harvest.

quick notes went to the wrong folder

Open onboarding again or edit ~/.claude/twin.config.json. Set quickNotesPath to a vault-relative folder like 📥 Inbox.

Custom sprites

Prompt and photo sprites use image generation plus optional background removal. The desktop onboarding can guide installation, or you can install it yourself:

$ pipx install "rembg[cpu,cli]"

/change-char creates a new character. /evolution iterates from the current sprite.