Claude Code + Obsidian: Build a Second Brain That Actually Thinks

Who this is for: Developers, researchers, or knowledge workers who take notes in Obsidian and want Claude Code to read, write, and act on their vault — not just answer questions about it.

Why This Combination Works

Claude Code has one fundamental problem: it forgets everything between sessions. Every time you start a new session, you're starting from scratch.

Obsidian has one fundamental advantage: everything is a plain Markdown file on your local disk. No API. No proprietary format. Just files.

Put them together and the problem disappears. Claude Code can read every note you've ever written, understand your thinking patterns, and pick up exactly where you left off — because your vault is its persistent memory.

Without Obsidian:    Session 1 ──X── Session 2 ──X── Session 3

                      (context lost)   (context lost)



With Obsidian vault: Session 1 ──→── Session 2 ──→── Session 3

                      (vault grows)    (vault grows)

The setup is surprisingly simple. Obsidian stores plain text. Claude Code reads plain text. No integration layer needed — just point Claude at your vault folder.

Part 1: Install Everything

Step 1 — Install Obsidian

Download from obsidian.md for your platform (macOS, Windows, Linux, iOS, Android). It's free.

On macOS via Homebrew:

brew install --cask obsidian

Create your vault:

mkdir ~/second-brain

Open Obsidian → "Open folder as vault" → select ~/second-brain.

Step 2 — Install Claude Code

# macOS

brew install --cask claude-code



# Windows

winget install Anthropic.ClaudeCode



# Linux

curl -fsSL https://claude.ai/install.sh | bash



# Verify

claude doctor

claude auth login

Requirements: Claude Pro ($20/mo) or Max subscription.

⚠️ npm install -g @anthropic-ai/claude-code is deprecated. Use the native installer.

Step 3 — Connect Them (30 seconds)

This is the whole "integration." Navigate to your vault in the terminal and run Claude Code:

cd ~/second-brain

claude

That's it. Claude Code now has full read/write access to every note in your vault. No plugins required. No API setup. No tokens to configure.

Run /init to generate a starter CLAUDE.md from your vault:

> /init

Claude will scan your folder structure, detect any existing patterns, and create a CLAUDE.md at the vault root. This file is loaded into every future session automatically.

Part 2: Vault Structure

Structure matters a lot here. Claude Code traverses directories, but deep nesting burns tokens on path resolution and leaves less room for actual note content. Flat is better.

Recommended Structure

~/second-brain/

├── CLAUDE.md                ← Claude's persistent context (auto-loaded)

├── .claude/

│   ├── settings.json        ← hooks config

│   └── skills/              ← vault automation skills

│       ├── daily/

│       │   └── SKILL.md

│       ├── research/

│       │   └── SKILL.md

│       └── weekly-review/

│           └── SKILL.md

├── daily/                   ← daily notes (YYYY-MM-DD.md)

│   └── 2026/

├── projects/                ← one folder per active project

│   ├── project-a/

│   └── project-b/

├── areas/                   ← ongoing responsibilities

├── resources/               ← reference material, clippings

├── _inbox/                  ← unprocessed capture

├── _attachments/            ← images, PDFs (Claude ignores these)

└── templates/               ← note templates

Naming conventions that help Claude:

Name files like sentences, not IDs. CAN-bus-traffic-without-DBC.md gives Claude usable context before reading a single line. untitled-48.md gives it nothing. Obsidian's backlink system and Claude's context signals both depend on the same thing: meaningful filenames.

Hide noise from Obsidian's file explorer:

In Obsidian → Settings → Files & Links → Excluded files, add:

_attachments/, .claude/, node_modules/

Part 3: CLAUDE.md for Your Vault

This is the most important file in the entire setup. Write it for the model, not for humans.

# Second Brain — Claude Context



## Who I Am

Software developer and technical writer. Based in London.

Main interests: distributed systems, developer tools, technical writing.



## Vault Structure

- `daily/` — daily notes, format YYYY-MM-DD.md

- `projects/` — active projects, one subfolder each

- `areas/` — ongoing responsibilities (writing, health, finance)

- `resources/` — reference notes, web clips, book notes

- `_inbox/` — unprocessed capture, process weekly



## Note Format

All notes use YAML frontmatter:

yaml

title: Note Title

date: 2026-04-10

tags: [tag1, tag2]

status: draft | active | archived

## Linking Conventions

- Use [[wikilinks]] for internal connections

- Tag topics with #tag-name (lowercase, hyphenated)

- Mark open tasks with `- [ ]`, completed with `- [x]`



## What Claude Can Do Here

- Create and edit notes following the format above

- Search vault using `grep -r "query" ~/second-brain/`

- Link related notes together

- Extract tasks from daily notes into project files

- Generate weekly summaries from daily notes

- Research topics and save findings to resources/



## What Claude Should NOT Do

- Never delete notes — move to _archive/ instead

- Never change a note's filename without asking first

- Never modify templates/ files

- Don't create files in _attachments/

shell

Keep it under 100 lines. Every line that stays should answer: "Would removing this cause Claude to make a mistake?"

Part 4: Getting Claude Inside Obsidian (Without Leaving the App)

Running between terminal and Obsidian is annoying. Three solutions, pick one:

Option A — Terminal Plugin (Simplest)

Install the Terminal community plugin by polyipseity:

Obsidian → Settings → Community plugins → Browse → search "Terminal" → Install → Enable.

Click the terminal icon in the left ribbon. A real terminal opens inside Obsidian. Run claude from there. You can see your notes and talk to Claude simultaneously.

Option B — MCP Bridge (Most Powerful)

Install the Obsidian Claude Code MCP community plugin by Ian Sinnott. It runs a dual-transport MCP server that exposes 7 structured tools to Claude Code:

# After installing the plugin in Obsidian, register it with Claude Code

claude mcp add obsidian-vault --transport sse http://localhost:27123/sse

Claude now has dedicated tools for vault operations — not just raw file reads. Works even when Obsidian is closed.

Option C — Sidebar Embed

Install Claude Sidebar by Derek Larson. Embeds a full Claude Code terminal directly in Obsidian's right panel. Click the bot icon in the ribbon → Claude opens beside your notes.

Best for: people who never want to leave Obsidian.

Part 5: The Core Workflows

Workflow 1 — Daily Note

Create .claude/skills/daily/SKILL.md:

---

name: today

description: Morning planning session. Use at the start of the day to create today's daily note and plan.

---



# Daily Note Workflow



1. Check if today's note exists at `daily/2026/YYYY-MM-DD.md`

   - If not, create it using the template at `templates/daily.md`

2. Read yesterday's daily note — extract any incomplete tasks

3. Read the current week's project notes — surface active priorities

4. Create today's note with sections:

   - ## Focus (top 3 priorities)

   - ## Tasks (carried over + new)

   - ## Notes (freeform capture)

   - ## End of day (leave empty)

5. Ask me if I want to add anything before finishing

Usage: Each morning, open terminal in vault and type:

> /today

Or just: "Run the today skill" — Claude matches by description.

Workflow 2 — Research and Capture

Create .claude/skills/research/SKILL.md:

---

name: research

description: Research a topic, synthesize findings, and save to resources/ folder.

---



# Research Workflow



When asked to research a topic:

1. Search the vault first — check if notes already exist

   `grep -r "topic" ~/second-brain/resources/`

2. Search the web for current information

3. Synthesize into a structured note:

   - ## Overview (what it is)

   - ## Key Concepts (the important parts)

   - ## Connections (links to existing vault notes)

   - ## Sources (URLs)

4. Save to `resources/topic-name.md` with proper frontmatter

5. Add [[wikilinks]] to related notes already in the vault

Usage:

> "Research Raft consensus algorithm and save to my vault"

> "Find everything I have on distributed systems and create a map of content"

Workflow 3 — Meeting Notes → Action Items

> "Read my note from the team meeting on 2026-04-08 and extract all action items assigned to me. Create tasks in projects/current-sprint/tasks.md"

Claude reads the meeting note, understands context, extracts your tasks specifically, and creates structured task items — linked back to the meeting note.

Workflow 4 — Weekly Review

Create .claude/skills/weekly-review/SKILL.md:

---

name: weekly-review

description: End-of-week review. Summarize the week, close open tasks, and plan next week.

---



# Weekly Review Workflow



1. Read all daily notes from this week (Mon–Fri)

2. Extract:

   - Completed tasks (✅)

   - Incomplete tasks (still open)

   - Themes and patterns across the week

   - New notes created in projects/

3. Generate weekly summary note at `daily/2026/YYYY-WW-weekly.md`:

   - ## What got done

   - ## What didn't (and why)

   - ## Patterns this week

   - ## Next week priorities

4. Ask: "Any wins or lessons you want to add before I save?"

Usage: Every Friday:

> /weekly-review

Workflow 5 — Connect the Dots

> "Read all notes tagged #distributed-systems from the last 3 months. Find recurring themes I haven't explicitly connected yet. Create a map of content note."

This is where the setup compounds. Claude has seen every note you've written. It finds connections you missed — not because it's smarter than you, but because it remembers everything you've captured over months.

Part 6: Vault CLAUDE.md vs Project CLAUDE.md

You can run Claude Code inside a code project that's separate from your Obsidian vault, and still give it access to vault context:

# In your code project

cd ~/projects/my-app



# Give Claude access to your vault knowledge base

claude --add-dir ~/second-brain/resources

Or use a symlink in your vault to pull project docs in:

cd ~/second-brain

ln -s ~/projects/my-app/docs project-docs

Now Claude sees both your code and your vault notes in the same session.

Part 7: Useful Plugins to Install

These are optional but make the experience noticeably better:

Install: Obsidian → Settings → Community plugins → Turn off Safe mode → Browse.

Part 8: Common Mistakes

Using vague prompts.

"Summarize my work" → Claude guesses.

"Summarize all notes tagged #client-work from the last two weeks and list open deliverables" → Claude executes.

Forgetting to update CLAUDE.md.

As your vault evolves, your context file goes stale. Review it monthly. Add a line at the top: Last updated: YYYY-MM-DD.

Letting Claude pollute your vault.

Your vault should contain your authentic thinking. Claude's outputs — plans, summaries, memory — should go into _claude/ or projects/ folders, clearly marked. Keep generated content separate from your own notes.

Deep nesting.

Projects/Active/Q1/Research/Sources/topic.md costs more tokens to work with than research/topic.md. Flatten where possible.

No consistent note format.

If some notes have YAML frontmatter and others don't, Claude has to guess at structure. Enforce templates from the start with Templater.

Part 9: What This Looks Like Day-to-Day

Morning (2 minutes):

cd ~/second-brain

claude

> /today

Claude reads yesterday's note, surfaces unfinished tasks, creates today's note. You review, add anything, close terminal.

During the day:

You take notes in Obsidian normally. Web clips, meeting notes, ideas. Claude isn't involved.

When you need research:

> "Research WebAssembly SIMD support and save to resources/"

Claude searches the web, checks what you already have in the vault, writes a structured note, links it to related notes.

End of week:

> /weekly-review

Claude reads all week's notes, generates the summary, asks for additions.

Over time:

The vault grows. Claude gets smarter about your specific context. The more you've written, the more connections it can surface. The system compounds.

The Honest Limitations

• Claude Code still has a context window. Very large vaults require targeted queries — Claude can't read 800 notes in one session.


• This requires terminal comfort. If command line is unfamiliar, the setup friction is real.


• Claude writes to your files. Review what it creates before treating it as your own thinking.


• Local only — no mobile sync out of the box. Use Obsidian Sync or git for cross-device.

Quick Start Summary

# 1. Install

brew install --cask obsidian

brew install --cask claude-code



# 2. Create vault

mkdir ~/second-brain

# Open Obsidian → "Open folder as vault"



# 3. Connect

cd ~/second-brain

claude

> /init



# 4. Edit CLAUDE.md to describe your vault structure



# 5. First real task

> "Create a minimal folder structure for a developer's second brain"



# 6. Install Terminal plugin in Obsidian so you never leave the app

That's the full setup. Start with the daily note workflow. Get that reliable first. Then add research and weekly review. The system will tell you what it needs next.

Based on xda-developers.com, starmorph.com/blog, mauriciogomes.com, dev.to/numbpill3d, mindstudio.ai, geeky-gadgets.com, and medium.com/@martk. April 2026.