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

read · retrieve snippets

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 once per capability · or use twin-md action in Terminal · same queue

Claude Desktop (separate app)

Optional parallel setup: npx twin-md init registers the same twin MCP in Anthropic’s Claude Desktop so that app can 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.

CLI power path: twin-md harvest · watch → ~/.claude/twin.md

integrations & permissions

Obsidian Markdown vault 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