twin

Remembers everything. Acts on all of it.

A self-building second brain that compiles your work into memory, then runs your day off it: briefings, calendar, tasks, health, and the web, handled before you ask. Not a place you file things. An agent that lives your life with you.

All local. Plain Markdown in a git repo you own, running on Claude Code with an optional Codex fallback. No database, no API keys, no servers to be down.

     

---

Obsidian is the IDE. The LLM is the programmer. The wiki is the codebase.

Built on Andrej Karpathy's LLM Wiki pattern, with kepano/obsidian-skills for Obsidian formats.

Typical AI memory vs. twin

Typical AI memory	twin
Re-derives answers from raw chunks on every query	Compiles each source into one Markdown graph
Nothing compounds	Knowledge compounds with every session
Opaque embeddings you can never read	Pages you open in Obsidian and browse
Answers you cannot trace	Every answer cites its source, or flags the gap
Remembers, and stops there	Acts on your day, not just your questions

Every page is one shape: a compiled-truth summary (rewritten as understanding evolves) sitting on a dated, append-only timeline (so history stays auditable). Git is the undo button. That same compiled memory drives a life-OS layer: a briefing that triages your calendar, tasks, and health, write access to Apple Reminders and Calendar, and a scout that surfaces things worth your time.

What it does

Remembers

Self-building wiki	Drop sources in; the agent files, links, dedupes, and summarizes them into the right domain.
Compiled truth + timeline	Current understanding plus the dated history of how it was learned, on every page.
Auto-capture	A SessionStart hook feeds context into new Claude Code sessions; SessionEnd backs them up. Per-project opt-in, so private work stays private.
Ask, with citations	twin ask reads the whole wiki, cites its sources, and flags gaps instead of guessing.

Acts

Daily briefing	twin morning triages your calendar, reminders, priorities, and health into one read on the Today screen.
Reminders + calendar	Read and write Apple Reminders and read every Apple Calendar via EventKit, no app launch. ingest even turns notes into reminders.
Health coaching	Turns your Apple Health export into deterministic recovery, sleep, and activity signals.
Proactive scout	Searches the outside world for events and deadlines ranked to your interests, and pings you on a hit.

Everywhere, and yours

Web app	A local React UI over the real vault: briefing, capture, ask, wiki reader, tasks, calendar, health.
Menu bar app	A native macOS companion for quick capture, on-device voice notes, and ask, one click away.
Token-budgeted	Scheduled jobs skip when nothing changed, run mechanical work on a cheap model, reason with the smart one.
Yours and safe	Plain Markdown in git. A secret scan runs before every push.

Quick start

Requires Claude Code, git, and python3. Install Codex as well to use the built-in fallback. The web app and Life-OS features also want Node.js and, on macOS, the Xcode Command Line Tools (swift). macOS gets the full set; Linux runs the CLI, wiki, and web app and skips EventKit cleanly.

# one line: clone the framework and install
curl -fsSL https://raw.githubusercontent.com/Arsh-S/twin-brain/main/bootstrap.sh | bash

# or read the code first
git clone https://github.com/Arsh-S/twin-brain.git && cd twin-brain
./install.sh --with-skills          # --dir PATH to choose where the brain lives (default ~/twin)

Either path creates your vault, puts twin on your PATH, installs the hooks and web app, schedules the jobs (macOS), then runs twin onboard: a guided setup with a live capture -> ingest -> ask demo. Your knowledge lives in the vault, separate from this framework repo, so you can keep it private.

The CLI

twin capture "a thought"                # drop into the inbox
twin clip https://example.com/article   # web page -> clean markdown
twin ingest                             # compile inbox + sessions into the wiki
twin ask "what do I know about X?"       # cited answer from the wiki
twin engine status                        # Claude first, Codex fallback by default
twin engine fallback off                  # disable automatic fallback
twin morning                            # 08:00 briefing: calendar + tasks + health + scout
twin app                                # launch the web UI (http://localhost:5179)
twin doctor                             # health check: deps, permissions, schedule, sync

In any other repo, Claude Code offers once to track that project in twin. Tracked projects get captured automatically; private ones never are.

Full command reference

twin onboard                            # guided first run + a live capture->ingest->ask demo
twin search "topic"                     # hybrid semantic + keyword search
twin tidy                               # cheap mechanical clean + sort into MOCs
twin lint                               # deep reconcile + health audit
twin research 3                         # fill ~3 web-research gaps (soft target)
twin scout                              # proactive web discovery -> "Worth your time"
twin remind "call the dentist" --due "June 20, 2026 9:00 AM"
twin remind search "invoice" --list Work   # search reminders (--all incl. done, --json)
twin agenda                             # briefing to generated/ (calendar + reminders + priorities)
twin health ingest | coach              # ingest Apple Health export, then coaching signals
twin bar build                          # macOS menu bar app (quick capture, voice notes, ask)
twin status

The apps

twin app boots a local React front-end over your live vault (no mock data). A browser cannot run EventKit or claude, so the Vite dev server doubles as the backend: every /api/* request shells out to the twin CLI, the Swift EventKit helpers, or the vault files. Nothing extra to deploy.

Nine screens (Today, Capture, Ask, Wiki, Tasks, Calendar, Health, Maintain, Settings) reachable with Option + 1 to 9, in a light or dark theme (the dashboard above is the Today screen).

Menu bar app (macOS)

twin bar build compiles a native SwiftUI companion, TwinBar.app, and installs it as a login agent (an LSUIElement: menu bar only, never the Dock). From the icon you get quick capture (⌘↩), on-device voice notes (SFSpeechRecognizer), inline ask, one-tap jobs, and live status. It drives the same twin CLI as everything else, so it stays correct as the CLI evolves.

twin bar build      # compile, sign, install the login agent, launch
twin bar status | restart | stop

How it works

capture --> raw-sources/ --> ingest (Claude) --> wiki/ --> ask / SessionStart recall
   ^            (immutable)       (compiles)     (the brain)          |
   +---------------------- compounding loop ---------------------------+
     nightly: ingest + tidy + sync   .   weekly: + lint + research + scout   .   morning: agenda

• raw-sources/ immutable inputs (you write; the agent only reads and moves them).
• wiki/ agent-owned compiled knowledge (projects/ learning/ personal/ concepts/ people/ maps/).
• generated/ one-off AI outputs (briefings, drafts), kept out of the wiki.
• bin/ the twin CLI plus Swift EventKit helpers. app/ the web UI and its API bridge.
• CLAUDE.md the schema that makes the agent a disciplined maintainer.

Scheduled jobs are idempotent: they stamp a last-run marker, skip if already run this day or week, and catch up exactly once if the Mac was off. The default engine order is the claude CLI, then Codex if Claude exits unsuccessfully. Configure it with twin engine. For a from-the-code walkthrough, see docs/ARCHITECTURE.md.

Privacy

This framework repo contains only functionality, never personal content. Your vault holds your data; keep it in a private repo, or no remote at all. A secret scan (API keys, tokens, private keys) runs before every twin sync and aborts the push on any hit. The capture hook skips private projects and twin's own directory.

License

MIT, see LICENSE.