DEV Community

mibii
mibii

Posted on

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

#obsidian #productivity #ai #claudecode

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Create your vault:

mkdir ~/second-brain
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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:
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode


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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

> /today
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Usage:

> "Research Raft consensus algorithm and save to my vault"
> "Find everything I have on distributed systems and create a map of content"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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?"
Enter fullscreen mode Exit fullscreen mode

Usage: Every Friday:

> /weekly-review
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

cd ~/second-brain
ln -s ~/projects/my-app/docs project-docs
Enter fullscreen mode Exit fullscreen mode

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:

Plugin What it adds
Templater Auto-create daily notes with consistent frontmatter
Dataview Query your vault like a database — Claude can write these queries
Periodic Notes Daily/weekly/monthly note creation on schedule
Smart Connections Semantic search via local embeddings
Terminal Run Claude Code inside Obsidian (see Part 4)
Web Clipper Save web pages to vault — Claude can then read and summarize them
Calendar Visual calendar for daily notes

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
Enter fullscreen mode Exit fullscreen mode

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/"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)