brain-os

Brain OS

Your AI tools give generic answers because they don't know how you think. Brain OS fixes that — it's a Claude Code plugin that turns your Obsidian vault into a second brain that learns, thinks, and acts with you.

Quick Start

One line. Plugin + vault + everything ready in under 2 minutes:

curl -sSL https://raw.githubusercontent.com/sonthanh/brain-os-plugin/main/install.sh | bash

Already have an Obsidian vault? Point to it:

curl -sSL .../install.sh | bash -s -- --vault ~/my-vault

Just want the plugin (no vault setup):

curl -sSL .../install.sh | bash -s -- --plugin-only

After install, try your first command:

/think What should I focus on this week?

Brain OS reads your context, goals, and recent activity — then thinks with you. Not generic advice. Your priorities, your situation.

Power feature: /study reads an entire book, extracts atomic notes, validates each one against NotebookLM (159/159 checks, avg 97/100 accuracy), and connects insights to your vault — fully autonomous.

See Getting Started for the full setup walkthrough and first use cases.

GitHub tasks setup

Tasks (/pickup, /handover, /status, /impl, /slice) live as GitHub issues in a repo you own — not in Markdown files. This solves multi-session concurrency (atomic state, stable IDs, no merge conflicts).

One-time setup:

1. Pick or create a GitHub repo you own (private or public) — e.g. your-username/my-tasks.
2. gh auth login if not already authenticated.
3. Set gh_task_repo: in ~/.brain-os/brain-os.config.md:

   gh_task_repo: your-username/my-tasks
   

4. Bootstrap the 15 labels (status, priority, weight, owner, type):

   R=your-username/my-tasks
   gh label create status:ready        --color 0E8A16 -R $R
   gh label create status:in-progress  --color 1D76DB -R $R
   gh label create status:blocked      --color B60205 -R $R
   gh label create status:backlog      --color C5DEF5 -R $R
   gh label create priority:p1         --color D93F0B -R $R
   gh label create priority:p2         --color FBCA04 -R $R
   gh label create priority:p3         --color FEF2C0 -R $R
   gh label create priority:p4         --color E1E4E8 -R $R
   gh label create weight:heavy        --color 5319E7 -R $R
   gh label create weight:quick        --color 006B75 -R $R
   gh label create owner:human         --color F9D0C4 -R $R
   gh label create owner:bot           --color BFDADC -R $R
   gh label create type:handover       --color FF6B6B -R $R
   gh label create type:plan           --color 8A2BE2 -R $R
   

Without gh_task_repo configured, skills silently skip the task panel and work in read-only vault mode.

Why Brain OS

Claude Code skills solve specific tasks. But context is scattered across projects, skills, and agents. Each one knows a piece — none sees the full picture. Decisions from fragmented context are generic: "correct but not yours."

Think of it like onboarding a team lead. You don't start by delegating decisions — you teach them how you think first. Give them the books you've read, the frameworks you use, the goals you're chasing. Then gradually let them act.

That's what Brain OS does with AI. One vault, one knowledge layer. Every skill reads from the same source of truth — your context, your knowledge, your decisions. The more you use it, the more it thinks like you.

Karpathy is building something similar with "LLM Knowledge Bases." Same direction, different purpose — he builds a wiki to read. Brain OS is an OS to act.

Read the full story: Day 1 — I Taught an AI to Read a Book

Skills

Learn — teach it what you know

Skill	When to use
/study	When you want to master a book end-to-end: extract, validate, absorb into your vault
/self-learn	When you want to extract and validate knowledge from a book (the core of /study)
/research	When you need to understand a topic — searches the web and synthesizes a cited report

Think — let it reason with you

Skill	When to use
/think	When you're stuck on a decision, exploring an idea, or want deep reflection on anything
/grill	When you need a plan stress-tested until it's bulletproof
/audit	One-shot principle check via advisor — non-interactive, returns findings

Act — let it work for you