Build a Second Brain with Claude Code and Obsidian¶

Most note-taking apps are graveyards. You clip an article, it sits in a folder, you never read it again. The knowledge doesn't connect to anything. It doesn't compound. After three years you have 4,000 notes and can't find anything.

This guide builds something different: a self-maintaining knowledge base where Claude Code acts as your librarian. You dump raw material in. Claude reads it, writes structured wiki articles, cross-links related concepts, and files everything. You ask questions. The answers become new notes. The library grows smarter every time you use it.

The architecture is based on Andrej Karpathy's LLM Wiki pattern: a persistent, compounding knowledge base where an LLM does the bookkeeping you'd never do yourself.

What You're Building¶

Browser Clipper
      ↓
  raw/          ← your inbox (you dump things here)
      ↓ compile
  wiki/         ← Claude's domain (structured articles, cross-linked)
      ↓ query
  output/       ← answers, reports, synthesis

Three folders. One rulebook (CLAUDE.md). Four verbs. That's the entire system.

Claude Code reads your raw material, decides what it means, writes wiki articles, and keeps a master index so it can navigate the whole library in future sessions. You never organize anything manually.

Part 1: Install the Tools¶

Claude Code¶

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

Obsidian¶

Download from obsidian.md and install. When it opens, create a new vault — a vault is just a folder on your computer. Name it something like brain and put it somewhere permanent (e.g. ~/brain).

Part 2: Build the Vault Structure¶

Open Claude Code inside your vault folder:

cd ~/brain
claude

Then give it this prompt:

Create this folder structure for my knowledge base:

- raw/ — this is my inbox where I'll dump source material
- wiki/ — this is your domain, you'll write and maintain everything here
- Create a _master-index.md inside wiki/ with the heading "Knowledge Base Index"
  and a note that says "Topics will be listed here as they are created."
- output/ — this is where query results and reports go

Just create the folders and that one file. Nothing else yet.

You should now have:

~/brain/
├── raw/
├── wiki/
│   └── _master-index.md
└── output/

Part 3: The CLAUDE.md Rulebook¶

This file is the librarian's instruction manual. Create CLAUDE.md at the root of your vault:

touch ~/brain/CLAUDE.md

Paste this content:

# Knowledge Base Rules

This is an LLM-maintained knowledge base. You are the librarian.

## Folder roles
- **wiki/** is YOUR domain. You write and maintain everything in it.
  I rarely edit wiki files directly.
- **raw/** is the inbox. When I dump files here, you process them
  into the wiki during a "compile" step.
- **output/** is for query results and generated reports.

## Structure rules
- wiki/_master-index.md is the entry point. It lists every topic folder
  with a one-line description. Always keep it up to date.
- Each topic gets its own subfolder in wiki/ (e.g., wiki/ai-agents/) with
  its own _index.md listing all articles with brief descriptions.
- Always use [[wiki links]] to connect related concepts across topics.
- Keep articles concise — bullet points over paragraphs.
- Include a ## Key Takeaways section in every wiki article.

## Compile workflow
When I say "compile", process everything in raw/ not yet compiled:
1. Read the raw file
2. Decide which topic it belongs to (or create a new one)
3. Write a wiki article with key takeaways and [[wiki links]] to related concepts
4. Update that topic's _index.md
5. Update wiki/_master-index.md
6. If a raw file spans multiple topics, create articles in both and cross-link

## Query workflow
When answering questions:
1. Read wiki/_master-index.md first to navigate
2. Drill into the relevant topic _index.md
3. Read specific articles
4. If I ask to save the answer, write it to output/ and link it to source articles

## Audit workflow
When I say "audit", walk the whole wiki and report:
- Broken [[wiki links]]
- Missing cross-references between related topics
- Gaps in coverage
- Inconsistencies between articles
Do not make changes yet — just give me the report.

This file is the system. Claude reads it at the start of every session and knows exactly how to behave.

Part 4: Connect Obsidian MCP¶

The MCP connection lets Claude read and write Obsidian notes natively — including backlinks, metadata, and the full vault graph. Without it, Claude can only use standard file tools. With it, it understands the vault as a vault.

What you need first¶

• Node.js 18+ (check: node --version)
• Claude Code 1.x or later (check: claude --version)
• Your vault path (e.g. ~/brain or /Users/you/brain)

Option A: Add via CLI (recommended)¶

Claude Code has a built-in command to register MCP servers. Run this once:

claude mcp add --scope user obsidian -- npx -y mcp-obsidian /Users/YOUR_USERNAME/brain

Replace /Users/YOUR_USERNAME/brain with your actual vault path. The --scope user flag adds it to your global user settings so it's available in every project, not just this one.

Verify it registered:

claude mcp list

You should see obsidian in the list with a status of connected or ready.

Option B: Edit settings.json manually¶

If you prefer to edit directly, open ~/.claude/settings.json and add the mcpServers block:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-obsidian",
        "/Users/YOUR_USERNAME/brain"
      ]
    }
  }
}

If mcpServers already exists in your settings, add the "obsidian" key inside it — don't replace the whole block.

Restart and verify¶

Restart Claude Code after adding the server:

claude

On startup, Claude Code initialises all registered MCP servers. You'll see a brief connection message for each one. If obsidian fails to connect, you'll see an error — the most common cause is a wrong vault path.

Test the connection with this prompt:

List all the files currently in my Obsidian vault and show me the contents 
of wiki/_master-index.md

If Claude returns your vault file tree and reads the index file, the MCP connection is working. If it falls back to plain file tools, the server didn't connect — double-check your path and restart.

What MCP gives you over plain files¶

For a simple wiki like this one, plain file tools cover 90% of use cases. MCP matters most when you start querying by tag, following backlinks across topics, or asking Claude to find notes that reference a specific concept.

Part 5: Give Claude Hands on the Web¶

A knowledge base that can only read files you manually add gets stale fast. These two tools let Claude pull fresh information autonomously.

Playwright — Browser Automation¶

Playwright lets Claude open a real browser, navigate pages, and capture what it sees.

Install the Playwright CLI:

npx playwright install

Test it:

Open a browser, go to news.ycombinator.com, and tell me the top 5 stories right now.

Claude will launch a browser, scrape the page, and return the content directly.

Firecrawl — Web Scraper¶

Firecrawl extracts clean content from any URL — no ads, no nav, just the text. Better than Playwright for articles and documentation.

npm install -g firecrawl-cli

Authenticate with your API key from firecrawl.dev:

firecrawl login --api-key fc-YOUR-API-KEY

Verify:

firecrawl --status

Test it:

firecrawl https://example.com --only-main-content

With both tools active, Claude can research any topic on demand — not just answer from what's already in the wiki.

Part 6: The Web Clipper¶

For saving articles while browsing, install the Obsidian Web Clipper browser extension (Chrome, Firefox, Safari).

Open the Web Clipper settings:

• Vault: select your vault (brain)
• Note location: raw
• Note name: {{date|date:"YYYY-MM-DD"}}-{{title|safe_name}}

Now one click saves any article directly into raw/ — date-stamped, ready to compile.

Part 7: The Four Verbs¶

The entire daily workflow is four words.

1. Clip¶

You see something worth keeping. One click. It lands in raw/. You don't organise it, summarise it, or decide where it goes. Just clip it.

2. Compile¶

Once a week (or when raw/ feels full), open Claude Code and type:

Compile everything in raw/ into the wiki. For each file:
1. Read it and identify the core topic
2. Create or find the right topic folder in wiki/
3. Write a wiki article with a summary, key takeaways, and [[wiki links]]
   to any related concepts
4. Update the topic's _index.md
5. Update wiki/_master-index.md

Cross-link between topics wherever relevant.

Claude processes every unread file, creates structured articles, and updates the index. You come back to a fully organised library.

3. Query¶

Ask the library anything.

Simple lookup:

What were the key findings from the article I clipped about PostgreSQL partitioning?

Cross-referencing:

How does the shift to AI coding assistants relate to what I've been 
reading about developer productivity?

Synthesis (the compound move):

Based on everything in the wiki, what are the strongest arguments 
for and against multi-agent AI systems in production?
Save your answer as a new wiki article and link it to the sources 
you referenced.

That last query is the move that makes the system compound. Every question becomes a new note. Every note links to its sources. The library gets smarter every time you use it.

4. Audit¶

Once a month:

Audit the wiki. Look for inconsistencies, broken links, missing 
cross-references, and gaps in coverage. Don't make changes yet, 
just give me a report.

Claude walks the whole library and tells you where it's getting fuzzy. You decide what to fix.

Part 8: Research on Demand¶

With Playwright and Firecrawl connected, you can go further than compiling what you've already clipped.

Pull a topic into the wiki automatically:

Research the current state of vector databases for AI applications.
Use Firecrawl to read the top articles. Then compile the findings 
into a new wiki topic at wiki/vector-databases/ and update 
_master-index.md.

Stay current on a subject:

Check Hacker News for any posts about PostgreSQL in the last week.
Clip anything relevant to wiki/databases/ and cross-link to 
existing articles.

Deep research with synthesis:

I need to understand how Patroni handles leader election. 
Read the official Patroni docs and the GitHub issues about 
etcd connectivity. Compile a wiki article at 
wiki/databases/patroni-leader-election.md with key takeaways 
and links to sources.

Summary¶

The system in one sentence: Obsidian holds the library, Claude Code is the librarian, and four verbs keep it alive.

Setup checklist¶

The four verbs¶

Why this works¶

Most knowledge systems fail because the maintenance cost is higher than the retrieval value. Filing, tagging, cross-referencing — you stop doing it within two weeks.

This system eliminates the maintenance cost entirely. You do one thing: clip what's interesting. Claude does everything else. The library grows with almost no friction, and every question you ask makes it smarter for the next one.

Based on Andrej Karpathy's LLM Wiki pattern. Built with Claude Code, Obsidian, Playwright, and Firecrawl.

Questions or discussion? Connect on LinkedIn, X or reach out via email.

Discussion

Have thoughts on this post? Share them below — questions, corrections, or your own experience are all welcome.