Obsidian Second Brain With Claude Code: Full Setup

An Obsidian second brain with Claude Code is a vault of plain markdown notes that an AI agent reads, links and keeps current for you. You add sources; Claude turns them into connected notes and answers questions with pointers to where each answer came from.

Obsidian holds the memory, and Claude does the bookkeeping nobody keeps up by hand.

This is the exact system I run my business on: notes about clients, offers, audits, decisions and competitors, maintained in Claude Code. It's also what I build for clients. Here's the full setup, including the part most tutorials skip: keeping the brain honest.

Why Obsidian and Claude Code work so well together#

Most second brains die the same way: capture is easy, maintenance is tedious, and after a few months the notes are a pile nobody trusts. AI changes the economics of maintenance, which is the idea behind Andrej Karpathy's LLM wiki pattern.

The pairing works because each tool does what it's best at:

• Obsidian stores notes locally as markdown, with links, backlinks, a graph view and thousands of plugins. It's free.
• Claude Code reads and writes files, runs scripts and follows written rules. It loads a CLAUDE.md file at the start of every session, so the rules persist.

No proprietary database sits in the middle. If you stop using either tool tomorrow, your notes are still readable files.

Step 1: Design the vault structure#

Separate what you collected from what the AI wrote. Here's a structure that works for most people, adapted from my own vault:

brain/
├── CLAUDE.md          the rules Claude follows
├── index.md           one line per note, updated on every ingest
├── log.md             append-only record of ingests and checks
├── raw/               sources: never edited by Claude
│   ├── articles/
│   ├── transcripts/
│   └── pdfs/
└── wiki/
    ├── entities/      people, companies, products, clients
    ├── concepts/      frameworks and ideas
    ├── decisions/     what was decided, why, and what would change it
    ├── sources/       one summary note per raw source
    └── answers/       good answers worth keeping

The decisions folder is the one I'd add to any business brain. Six months from now, "why did we do this?" is the question you'll ask most.

Step 2: Write the CLAUDE.md rules#

CLAUDE.md is the brain's constitution. Anthropic's memory documentation recommends keeping it under 200 lines and making each instruction specific enough to verify. Mine centers on rules like these:

• Files in raw/ are read-only.
• Every note in wiki/ links to at least one source note that supports it.
• Every ingest updates index.md and appends a dated line to log.md.
• When a new source contradicts an existing note, add a "Conflicts" section to both notes instead of silently overwriting.
• Numbers are claims. A figure without a linked source is marked as unverified.
• Use existing entity notes before creating new ones; search the index first.

For the mechanics of loading and structuring the file, see my guide to writing CLAUDE.md.

Step 3: Add three skills#

Skills package workflows that load only when needed, so they don't bloat every session. Three cover almost everything:

1. Ingest. Read one source from raw/, write a source summary, update or create the related entity and concept notes, update the index and the log, then report what changed.
2. Ask. Answer a question using the index and the linked notes, cite the notes used, and offer to save the answer to wiki/answers/.
3. Lint. Find orphan notes, broken links, contradictions, stale claims and numbers without sources, and produce a short report to fix.

Put each in .claude/skills/<name>/SKILL.md inside the vault. If you're new to the format, read how to build Claude skills. The lint skill is where a small script pays off: counting orphans and unsourced figures should be code, not judgment.

Step 4: Run your first week#

Open Obsidian, open a terminal in the vault folder, and run claude. Then:

• Days 1 and 2: ingest five sources on one topic, one at a time. Read each summary and correct what's off. Those corrections become better rules.
• Day 3: ask ten real questions. Save the good answers.
• Day 4: run lint and fix what it finds.
• Day 5: tighten CLAUDE.md based on everything you corrected.

Keep Obsidian's graph view open while you work. Hubs and orphans show up visually long before they show up in answers.

Step 5: Keep the second brain honest#

This is the step that separates a useful second brain from a confident one. AI summaries turn estimates into facts, and repetition makes them look authoritative. Months later, a number sits in five notes and nobody remembers where it came from.

In my marketing brain every figure has to trace to a claim with an evidence class: a documented constraint, a mechanism, a convention with no direct evidence, or a local measurement. A linter fails the build when a note states a number that no claim supports. It sounds strict. In practice it's the reason I trust what the brain tells me.

You don't need a full evidence system on day one. Start with one rule: no source link, no number.

Connecting the brain to the rest of your tools#

Once the core works, extend it carefully:

• Add the Claude Code IDE plugin so Claude sees the note you're working on.
• Connect an Obsidian MCP server if you also want Claude Desktop to search the vault.
• Commit the vault to a private Git repository for history and rollback.
• Schedule a weekly lint run.

Community projects show how far this can go. The open-source obsidian-second-brain project adds scheduled agents for morning briefs and nightly consolidation on top of Karpathy's design. I'd still add automation only after the manual loop works.

Want it built for you?#

Setting this up well takes a weekend for a personal brain and more for a team, mostly in writing the rules and skills around how you actually work. If you'd rather start with a brain built around your own sources, conventions and evidence rules, that's exactly what my AI Brains are. If you're still comparing tools, read Obsidian vs Notion for an AI second brain first.