install

get your twin running

Download the macOS desktop build, then choose your Obsidian or Markdown vault during onboarding. Node 20+ is only needed if you want the CLI/MCP tools or local development.

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. Twin uses that folder for retrieval and restore.

download latest release →

Optional: Claude Desktop wiring

Use this only if you want the CLI and MCP bridge. New users can skip it at first.

CLI setup

This seeds Twin context and registers the MCP server for Claude Desktop.

$ npx twin-md init

You do not need to memorize generated file paths. The desktop app and CLI manage the setup.

$ twin-md action approve <id>

Desktop handoffs start as needs_approval. Approve in the app or Terminal; saved capabilities like Spotify, Playwright, and Reminders can run faster next time.

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:

$ twin-md watch
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.

twin-md command not found

Install globally: npm install -g twin-md

pet shows blank / default state

Run twin-md harvest to pull fresh signals. The companion auto-updates.

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.