architecture

your vault stays the center

Everyday chat is local-first. The app prefers your installed Claude Code or Codex CLI, injects the bundled twin MCP server, and streams the reply into Twin—no Claude Desktop window required for typing in the app. When an Obsidian vault is configured, that vault is the notes root for retrieval and MCP tools; the fallback ~/twin-brain tree is only used when there is no vault. Provider API keys are optional: use them for custom sprites, chat backgrounds, and (if you skip the CLI) in-app chat over HTTPS to Anthropic, OpenAI, or Gemini.

system map

Solid: main path. Dashed: optional Claude Desktop for queued actions.

You

onboarding · picks vault

Twin.md

desktop app · chat · companion · Rust IPC

Vault

Obsidian / Markdown folder · primary notes root

read · retrieve snippets · create quick notes

Local chat

Claude Code or Codex CLI on your Mac, with twin MCP wired in—answers stay in the subprocess, not in a browser tab.

default for conversation

Action queue

local JSONL on disk

Spotify · Playwright · Reminders…

Optional provider keys

Add Anthropic, OpenAI, or Gemini in settings when you want AI-generated sprites, scene wallpapers, or cloud API chat without installing the CLI. Keys are not required to use vault tools or the local CLI path.

Permission center

Approve each request in-app · or use twin-md action in Terminal · same queue

Claude Desktop (separate app)

Optional source setup registers the same twin MCP in Anthropic’s Claude Desktop so that app can read the configured Obsidian vault, poll the action queue, run computer-use, and resolve items. This does not replace in-app chat—it is an extra surface for power workflows.

Real desktop & apps

OS-level work happens here after approval—not silently in someone else’s cloud.

Source CLI path: node packages/cli/dist/bin.js harvest → ~/.claude/twin.md

integrations & permissions

Obsidian primary notes root Claude Code local chat · CLI + twin MCP Claude Desktop optional · MCP + actions OpenAI optional · sprites & backgrounds Gemini optional · sprites & backgrounds Spotify after approve Playwright after approve Reminders after approve