:classical_building: claude-second-brain

Your notes don't compound. This wiki does.

The fastest way to start your personal knowledge base powered by Obsidian, Claude Code, qmd, and GitHub.

npx claude-second-brain

One command gives you a fully wired knowledge system:

• Claude ingests your sources and maintains a cross-linked wiki
• qmd powers local semantic search
• The scaffolded folder is your Obsidian vault — open it directly in Obsidian, with obsidian-git pre-configured for seamless sync
• GitHub is the source of truth — version history, anywhere access, and a backup you control

You've been reading papers, articles, and books for years. Drop a source in, run /brain-ingest, and Claude reads it — extracts what matters, cross-links it to everything you already know, and files it. Ask a question six months later and get cited answers, not a list of files to re-read.

Inspired by Andrej Karpathy's approach to LLM-powered knowledge management — share an "idea file" with an LLM agent and let it build and maintain your knowledge base.

How this is different

This is not a RAG system. It's not a chatbot over your notes. It's an actively maintained, cross-linked wiki — five structured page types, YAML frontmatter, and a set of Claude Code skills that run the whole thing.

The schema (CLAUDE.md) is that idea file. Claude reads it every session.

The stack

| Tool | Role | |---|---| | Claude Code | Reads sources, writes wiki pages, cross-links, flags contradictions | | qmd | Local hybrid search (vector + BM25) across your entire wiki | | Obsidian | Graph view, backlinks, mobile reading — offline, no extra sync | | GitHub | Source of truth — version history, Claude Code anywhere, Obsidian sync |

Everything is pre-configured. You bring the sources.

Get started in 3 steps

Step 1 — Scaffold

npx claude-second-brain

Or install globally — csb is a shorter alias:

npm i -g claude-second-brain
csb

The CLI will ask:

• Brain name — what to call this brain (default: my-brain)
• GitHub repo — optionally create a private repo and push automatically (requires gh CLI)

Creates the brain at ~/.claude-second-brain/my-brain/, registers it in ~/.claude-second-brain/config.toml, installs mise + node + pnpm, runs pnpm install, and git init.

Step 2 — Generate vector embeddings

cd ~/.claude-second-brain/my-brain
pnpm qmd:reindex

First run downloads ~2GB of GGUF models — once per machine. qmd collections are already registered by the CLI during scaffolding.

Step 3 — Open in Obsidian (and push to GitHub if not done)

If you created a GitHub repo during setup, it's already pushed — skip straight to opening in Obsidian.

If you skipped GitHub during setup, connect it now:

git remote add origin https://github.com/you/my-brain.git
git push -u origin main

Open ~/.claude-second-brain/my-brain/ as a vault in Obsidian — the folder is already a valid Obsidian vault. The Git plugin is pre-configured — enable it and sync is automatic.

Claude Code skills included

The wiki ships with a set of slash commands that cover the full workflow. No manual prompting, no copy-pasting.

Daily workflow

/brain-ingest — Drop a file into raw-sources/articles/, raw-sources/pdfs/, or raw-sources/personal/. Run /brain-ingest. Claude summarizes the source, asks what matters most to you, creates a wiki/sources/ page, updates or creates related topic pages, flags any contradictions with existing knowledge, and logs everything.

/brain-search — Ask anything about what you know. Claude runs hybrid semantic search across the wiki, reads the most relevant pages, and writes an answer with inline [[wiki/page]] citations. If the answer synthesizes multiple pages in a novel way, it offers to file it as a permanent wiki/qa/ entry.

/lint — Health-check the wiki. Surfaces orphan pages, broken links, unresolved contradictions, and data gaps. Reports findings and applies fixes where possible.

Maintenance

/brain-refresh — Re-scan the vault for new or changed files and regenerate vector embeddings. Run after a bulk ingest session or manual edits. Pass force to re-embed every chunk (e.g. after changing the embedding model).

/brain-rebuild — Destructive. Redesigns the qmd schema: analyzes the wiki, proposes new collections and contexts, waits for your approval, then patches scripts/qmd/setup.ts, drops the old index, and rebuilds embeddings from scratch. Use only when the current structure no longer fits how you search.

Access from anywhere

Edit anywhere — Claude Code on desktop or mobile Claude Code's GitHub integration lets you open the repo and work from anywhere — ingest a source, run a query, or update a page from your phone.

Read anywhere — Obsidian desktop and mobile Open the repo as an Obsidian vault. The bundled .obsidian folder pre-configures the obsidian-git community plugin — no setup required, just enable it. Your wiki syncs automatically on every commit. For iOS: put the repo folder inside iCloud Drive — Obsidian Mobile picks it up natively with no extra setup. Graph view, backlinks, offline reading — all working.

Browse anywhere — GitHub It's a plain GitHub repo. View and edit files directly in the browser at any time.

How it works

Sources flow in on the left, Claude synthesizes them into the wiki, qmd indexes every page into a local hybrid search index, and GitHub makes the whole vault editable from Obsidian and Claude Code on any device.

flowchart TB
  subgraph Sources["raw-sources/ — raw, immutable"]
    direction LR
    S1[articles/]
    S2[pdfs/]
    S3[personal/]
  end

  subgraph Skills["Claude Code skills"]
    direction LR
    I["/brain-ingest"]
    Q["/brain-search"]
    R["/brain-refresh"]
  end

  subgraph Wiki["wiki/ — cross-linked synthesis"]
    direction LR
    W1[overview.md]
    W2[topic / entity pages]
    W3[sources/]
    W4[qa/]
  end

  QMD[("qmd.sqlite<br/>vector + BM25<br/>hybrid index")]

  subgraph Remote["GitHub — source of truth"]
    GH[private repo]
  end

  subgraph Read["Read / edit anywhere"]
    direction LR
    OB["Obsidian<br/>graph · backlinks · mobile"]
    CC["Claude Code<br/>desktop + mobile"]
  end

  User((you))

  Sources -->|read| I
  I -->|write pages, cross-link,<br/>flag contradictions| Wiki
  R -.->|chunk + embed<br/>changed files| QMD
  Wiki -.->|indexed by| QMD
  User -->|ask a question| Q
  Q -->|hybrid search| QMD
  QMD -->|top-k pages| Q
  Q -->|cited answer| User
  Wiki <-->|"obsidian-git<br/>auto commit / pull"| GH
  GH --> OB
  GH --> CC

The ingest loop, zoomed in

┌─────────────────────┐        ┌─────────────────────┐        ┌─────────────────────┐
│   Drop in a source  │        │ /brain-ingest       │        │     Wiki grows      │
│                     │        │        Code         │        │                     │
│  · article          │──────▶ │                     │──────▶ │  · cross-linked     │
│  · PDF              │        │  reads + extracts   │        │    pages            │
│  · personal note    │        │  key knowledge      │        │  · contradictions   │
│                     │        │                     │        │    flagged          │
└─────────────────────┘        └─────────────────────┘        │  · syntheses        │
                                                              │    written          │
                                                              └─────────────────────┘

Query it anytime with /brain-search. Get answers with inline [[wiki/page]] citations, not a list of files.

Wiki structure

Five page types, all with YAML frontmatter:

| Type | File | Purpose | |---|---|---| | overview | wiki/overview.md | Evolving high-level synthesis | | topic | wiki/[concept].md | A concept, domain, or idea | | entity | wiki/[name].md | A person, tool, company, or project | | source-summary | wiki/sources/[slug].md | One page per ingested source | | qa | wiki/qa/[slug].md | Filed answers to notable queries |

All pages cross-link with Obsidian [[wikilinks]]. Contradictions are flagged with [!WARNING] callouts. Full schema in CLAUDE.md.

Directory layout

All brains live under ~/.claude-second-brain/. A central config.toml tracks them.

~/.claude-second-brain/
├── config.toml            ← Brain registry (default brain, paths, git remotes)
└── my-brain/
    ├── CLAUDE.md          ← The schema. Claude reads this every session.
    ├── raw-sources/       ← Your raw inputs. Claude never modifies these.
    │   ├── articles/
    │   ├── pdfs/
    │   └── personal/
    ├── wiki/              ← Claude owns this entirely.
    │   ├── index.md
    │   ├── log.md
    │   ├── overview.md
    │   ├── sources/
    │   └── qa/
    ├── scripts/qmd/       ← Semantic search setup and re-indexing
    └── .qmd/              ← qmd index (gitignored)

Multiple brains

Run npx claude-second-brain again to create additional brains. Each gets its own folder, its own qmd index, and its own git remote — fully isolated. The global skills (/brain-ingest, /brain-search, /brain-refresh) always operate on the default brain declared in config.toml. The first brain you create is set as the default automatically.

Manage brains from the CLI (csb is the short alias — swap for npx claude-second-brain if not installed globally):

csb ls                             # list all brains (default marked with *)
csb use <name>                     # switch the default brain
csb rm <name>                      # remove a brain (deletes its folder + config entry)
csb path                           # print the default brain's directory
csb path qmd                       # print the default brain's qmd index path
csb path config                    # print ~/.claude-second-brain/config.toml
csb qmd query -c wiki "<terms>"    # run qmd against the default brain
csb exec -- pnpm qmd:reindex       # run any command inside the default brain
csb doctor                         # verify tools, config, and each brain

Every subcommand accepts --help for details (csb rm --help, csb path --help, …).

Installing and updating skills

Skills are slash commands Claude Code loads from .claude/skills/[name]/SKILL.md. /brain-ingest, /brain-search, and /brain-refresh install globally to ~/.claude/skills/ during setup so they work in any Claude Code session. /brain-rebuild and /lint live inside the vault at .claude/skills/.

Update the built-in wiki skills

The wiki's own skills are scaffolded at creation time. To pull in improvements, use npx skills pointing to the template skills directory in this repo:

# Install or update all 5 wiki skills from the latest template
npx skills add https://github.com/jessepinkman9900/claude-second-brain/tree/main/template/.claude/skills -a claude-code -y

# Or update a specific skill
npx skills add https://github.com/jessepinkman9900/claude-second-brain/tree/main/template/.claude/skills --skill brain-ingest -a claude-code -y

Once installed via npx skills, future updates are a single command:

npx skills update -a claude-code

Roadmap

• [ ] GitHub Actions to invoke /brain-refresh on a schedule
• [ ] GitHub agentic workflows — auto-ingest on push, scheduled lint, auto-summary on new sources
• [ ] More Claude Code skills (source discovery, topic clustering)

Requirements

• mise — auto-installed by the CLI if missing
• Claude Code — the CLI that runs the wiki
• Obsidian — optional but recommended

License

MIT