Obsidian + Claude Code: The Complete Integration Guide

Obsidian and Claude Code are two of the most powerful tools in a developer's toolkit right now — but using them together isn't obvious. Claude Code generates markdown files constantly (plans, memory, CLAUDE.md configs), and Obsidian is the best markdown editor on the planet. The problem? If you open a code repo as an Obsidian vault, you get PNGs, JavaScript files, JSON configs, and node_modules cluttering your file explorer.

I researched blog posts, Twitter threads, YouTube videos, GitHub repos, and Obsidian forum discussions to compile every strategy the community has found. This guide covers five distinct approaches, from simple file filtering to MCP bridges, so you can pick the one that fits your workflow.

The Problem
Strategy 1: Dedicated Developer Vault with Symlinks
Strategy 2: Vault IS the Claude Code Working Directory
Strategy 3: MCP Bridge
Strategy 4: One Vault Per Repo
Strategy 5: QMD + Session Sync
Fixing the File Clutter Problem
Recommended Plugins
Dataview Queries for Claude Code Files
The Obsidian CLI Game-Changer
Key Community Insight
Sources

The Problem

Claude Code stores its configuration across multiple locations:

~/.claude/CLAUDE.md — global instructions
~/.claude/plans/ — plan files for implementation tasks
~/.claude/projects/ — per-project memory files
~/.claude/skills/ — reusable skill definitions
{repo}/CLAUDE.md — per-project instructions (checked into each repo)

If you work across multiple repos, these files are scattered everywhere. Opening a code repo as an Obsidian vault technically surfaces the markdown, but also dumps every PNG, JS file, lock file, and node_modules directory into your file explorer.

Obsidian's built-in "Excluded Files" setting (Settings > Files & Links) helps, but it only does a soft exclude — files are hidden from some views but still indexed internally. It doesn't fully solve the problem.

Strategy 1: Dedicated Developer Vault with Symlinks

Best for: developers working across multiple repos who want unified search.

Create a dedicated Obsidian vault that's separate from any code repo. Use directory symlinks to pull in the files you care about.

# Create a dedicated vault (NOT inside any repo)
mkdir ~/Developer-Vault
cd ~/Developer-Vault

# Symlink your Claude Code global config
ln -s ~/.claude claude-global

# Symlink each project
ln -s ~/projects/my-app my-app
ln -s ~/projects/my-api my-api

Then configure .obsidian/app.json to filter out code noise:

{
  "userIgnoreFilters": ["node_modules/", ".next/", "dist/", ".git/", ".vercel/"]
}

Install File Explorer++ to filter by extension (hide *.js, *.ts, *.png, etc.).

What you get

Unified search across all CLAUDE.md files, plans, memory, and skills
Dataview queries spanning all projects
Cross-linking between project notes
No .obsidian/ clutter in your actual repos

Gotchas

Obsidian only supports directory symlinks, not individual file symlinks
Symlinks can cause issues on Obsidian Mobile — exclude from mobile sync
The Obsidian Git plugin only tracks one repo (the vault's own), not symlinked repos
Moving files across symlink boundaries in the Obsidian file explorer doesn't work

Strategy 2: Vault IS the Claude Code Working Directory

Best for: personal knowledge management / "second brain" workflows.

The most popular approach on Twitter and blogs. Your Obsidian vault is the directory you run claude from. CLAUDE.md at the vault root serves double duty — instructions for Claude and a readable note in Obsidian.

my-vault/
├── CLAUDE.md              # Claude reads this + Obsidian displays it
├── .claude/               # Skills, hooks, settings
├── daily-notes/
├── projects/
│   ├── pixelmuse/
│   └── my-api/
├── research/
├── decisions/
└── templates/

Key patterns from the community:

CLAUDE.md at root = vault operating manual
VAULT-INDEX.md = live dashboard Claude reads first
Per-folder index.md files that Claude auto-updates when creating or deleting files

The ballred/obsidian-claude-pkm starter kit adds goal cascading with yearly, monthly, and weekly goals. Noah Vincent's IPARAG structure organizes by Inbox, Projects, Areas, Resources, Archives, and Galaxy (Zettelkasten).

This works best when your vault is your project — not when you already have repos with established structures.

Strategy 3: MCP Bridge

Best for: keeping repos clean while giving Claude access to your knowledge base.

Run Claude Code in your repo directory as normal. An MCP server running inside Obsidian lets Claude query your vault without it being the working directory.

The obsidian-claude-code-mcp plugin auto-discovers vaults via WebSocket on port 22360. Multiple vaults are supported with unique port configurations.

# You're working in your app repo
cd ~/projects/my-app
claude

# Claude Code can simultaneously query your Obsidian vault
# for notes, plans, and context — no symlinks needed

The Claudesidian MCP plugin goes further with semantic search via Ollama embeddings and full agent-mode capabilities.

Trade-off: Requires Obsidian to be running. Another moving part in your stack.

Strategy 4: One Vault Per Repo

Best for: simple setups with single-project focus.

Open each repo as its own Obsidian vault. Use userIgnoreFilters to hide non-markdown files (see the file clutter fix below).

Add .obsidian/ to your .gitignore:

gitignore

# Obsidian
.obsidian/
.trash/

Downside: No cross-project search. Must switch vaults constantly. Can't see global ~/.claude/ plans alongside project files.

Strategy 5: QMD + Session Sync

Best for: heavy Claude Code users who want persistent memory across sessions.

This is the power user stack, championed by Shopify CEO Tobi Lutke's QMD tool:

QMD — semantic search over your markdown vault (60%+ token reduction vs grep/glob)
sync-claude-sessions — auto-exports Claude Code sessions to markdown on close
/recall skill — pulls relevant context before starting a new session

All local, no cloud. Claude Code sessions become searchable notes in your vault. Developer @ArtemXTech documented this stack and reported dramatically improved context recall.

Kevin Lee reported that updating all Claude Code skills with semantic chunking from QMD reduced token usage and processing time by over 60%.

Fixing the File Clutter Problem

If you're already using a code repo as an Obsidian vault and seeing PNGs and assets everywhere, here's the fix.

Step 1: Exclude directories via app.json

Open Settings > Files & Links > Excluded Files, or edit .obsidian/app.json directly:

{
  "userIgnoreFilters": ["node_modules/", ".next/", "dist/", ".git/", ".vercel/", "public/"]
}

Step 2: Exclude file types with regex patterns

In the same Excluded Files setting, add regex patterns wrapped in forward slashes:

/.*\.png/
/.*\.jpg/
/.*\.jpeg/
/.*\.svg/
/.*\.gif/
/.*\.ico/
/.*\.webp/
/.*\.js/
/.*\.ts/
/.*\.tsx/
/.*\.jsx/
/.*\.css/
/.*\.json/
/.*\.lock/

Important: This is a soft exclude. Files are hidden from search and graph view but still indexed internally by Obsidian.

Step 3: Install File Explorer++ for hard filtering

The File Explorer++ plugin supports wildcard/regex filters on file names and paths. You can toggle filters on and off, which is much more practical than the built-in settings.

Step 4: Turn off "Detect all file extensions"

In Settings > Files & Links, turn OFF "Detect all file extensions." This hides file types that Obsidian can't natively handle (JS, TS, JSON, etc.) from the explorer.

Alternative: File Ignore plugin

The File Ignore plugin uses .gitignore-style patterns and physically renames matched files with a dot prefix so Obsidian completely skips them during indexing. This is the most thorough solution but it physically modifies filenames.

Recommended Plugins

Must-Have for Developer Vaults

Plugin	Why
File Explorer++	Filter by wildcard/regex. Hide `.js`, `.png`, etc. Toggle filters on/off
Dataview	Query across all CLAUDE.md files, list plans by status, aggregate metadata
Templater	Create CLAUDE.md templates with standard sections

Claude Code Inside Obsidian (Pick One)

Plugin	Approach
Claudian	Embeds Claude Code as sidebar chat. Permission modes (YOLO/Safe/Plan)
Agent Client	Claude Code, Codex, and Gemini CLI in a side panel. Supports @mentions of notes
Claude Sidebar	Embedded terminal, auto-launches Claude Code, multiple tabs

MCP Plugins (Remote Access)

Plugin	Approach
obsidian-claude-code-mcp	Claude Code discovers vaults via WebSocket. No need to `cd` into vault
Claudesidian MCP	Full agent-mode MCP with semantic search via Ollama embeddings

Other Useful Developer Plugins

Plugin	Purpose
Folder Note	Attach a note to a folder. Click folder to open its note
File Hider	Right-click individual files/folders to hide them
Hide Folders	Pattern-based folder visibility toggle in file navigator

Dataview Queries for Claude Code Files

If you add frontmatter to your CLAUDE.md files, Dataview becomes extremely powerful.

Add frontmatter to each CLAUDE.md

---
type: claude-config
project: my-app
stack: [nextjs, tailwind, supabase]
status: active
---

Query all project configs

```dataview
TABLE project, stack, status
FROM ""
WHERE type = "claude-config"
SORT project ASC
```

List all Claude plans by last modified

```dataview
TABLE file.mtime as "Last Modified"
FROM "claude-global/plans"
SORT file.mtime DESC
```

Templater template for new CLAUDE.md files

---
type: claude-config
project: <% tp.system.prompt("Project name") %>
status: active
date: <% tp.date.now("YYYY-MM-DD") %>
---

# <% tp.system.prompt("Project name") %> — Claude Code Configuration

## Tech Stack

-

## Code Quality

-

## Key Architecture

-

## Env Vars

-

The Obsidian CLI Game-Changer

Obsidian 1.12 introduced a CLI that dramatically changes the integration story. Kepano (Obsidian CEO) announced that any agent — Claude Code, Codex, Gemini CLI — can now use Obsidian natively.

Developer @drrobcincotta benchmarked it on a 4,663-file, 16 GB research vault:

Finding orphan notes: grep took 15.6s vs CLI at 0.26s — 54x faster
Vault search: grep 1.95s vs CLI 0.32s — 6x faster

The three ways to connect Claude Code to Obsidian, ranked:

Obsidian CLI (fastest, most token-efficient)
REST API via community plugins
Filesystem access via grep/glob (slowest, most expensive)

Kepano is also building official Claude Skills for Obsidian to help Claude Code edit .md, .base, and .canvas files.

Key Community Insight

The #1 rule from Greg Isenberg and InternetVin's viral workflow video (59 min, 2026):

"Agents read, humans write."

Your vault should contain your authentic thinking. Claude reads it for context but shouldn't pollute it with generated content. Keep Claude's outputs (plans, memory) in ~/.claude/ and your knowledge in the vault proper.

Custom slash commands from their workflow:

/my-world — loads full vault context
/today — morning planning from daily notes
/close — evening reflection
/trace — track how an idea evolved over months
/ghost — answer in your voice using vault context