Comprehensive Guide to Integrating Obsidian with Claude Code for Open‑Source AI Knowledge Management

Core Pain Point – Scattered Files and Vault Chaos

Claude Code stores configuration in multiple locations ( ~/.claude/CLAUDE.md, ~/.claude/plans/, ~/.claude/projects/, ~/.claude/skills/, {repo}/CLAUDE.md). Opening a code repository directly as an Obsidian vault brings non‑markdown assets (images, scripts, node_modules, etc.) into the file list. Obsidian’s built‑in “exclude files” feature only hides them softly; they remain indexed and clutter the view.

Five Integration Strategies

Strategy 1 – Independent Developer Vault + Directory‑Level Symlinks

Suitable scenario: Maintaining many projects while wanting a single searchable vault.

Create a vault outside any repository and symlink the directories you need:

# Create independent vault
mkdir ~/Developer-Vault
cd ~/Developer-Vault
# Link Claude global config
ln -s ~/.claude claude-global
# Link individual projects
ln -s ~/projects/my-app my-app
ln -s ~/projects/my-api my-api

Configure .obsidian/app.json to filter out noisy folders:

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

Combine with the File Explorer++ plugin to hide extensions such as *.js, *.ts, *.png. Benefits:

Unified search of all CLAUDE.md, plans, memories, and skills.

Cross‑project Dataview queries.

Projects stay clean – no .obsidian/ pollution.

Caveats: Obsidian only supports directory‑level symlinks; single‑file links are not possible. Mobile symlink support is unstable; avoid syncing linked directories. Obsidian Git tracks only the vault, not the linked content.

Strategy 2 – Vault = Claude Code Working Directory

Suitable scenario: Personal knowledge‑base or “second brain”. Use the vault itself as Claude Code’s workspace. The root CLAUDE.md doubles as Claude’s instruction file and an Obsidian note.

my-vault/
├── CLAUDE.md          # read by Claude and Obsidian
├── .claude/           # skills, hooks, config
├── daily-notes/
├── projects/
│   ├── pixelmuse/
│   └── my-api/
├── research/
├── decisions/
└── templates/

Community examples (e.g., ballred/obsidian-claude-pkm) add a VAULT-INDEX.md for Claude and per‑folder index.md auto‑maintained by Claude. This works well when the vault is the primary work area, but feels forced if you already have a mature repository structure.

Strategy 3 – MCP Bridge

Suitable scenario: Keep repositories clean while allowing Claude to read knowledge. Separate code and Obsidian, then bridge them with a Message‑Channel‑Protocol (MCP) plugin. Claude runs in the project directory, but can query Obsidian via a WebSocket (default port 22360). Example plugins: obsidian-claude-code-mcp – GitHub: https://github.com/iansinnott/obsidian-claude-code-mcp Claudesidian MCP – GitHub: https://github.com/ProfSynapse/claudesidian-mcp (adds Ollama‑based semantic search). Advantages: No repository pollution, no symlinks. Direct access to notes, plans, and memories. Trade‑offs: Obsidian must stay running. Introduces an extra MCP layer, increasing system complexity. Strategy 4 – One Vault per Repository Suitable scenario: Single‑project focus with simple configuration. Treat each repository as its own vault and hide non‑markdown files via userIgnoreFilters in .obsidian/app.json . Add .obsidian/ and .trash/ to .gitignore to avoid polluting the repo: <code># Obsidian .obsidian/ .trash/</code> Pros: minimal setup, no extra structure. Cons: No cross‑project search. Cannot see global Claude plans ( ~/.claude/ ). Switching between vaults is cumbersome. Strategy 5 – QMD + Session Sync Suitable scenario: Heavy Claude Code users who want persistent conversation context. Combine Shopify CEO Tobi Lutke’s QMD (GitHub: https://github.com/tobi/qmd) with the sync-claude-sessions tool and a /recall skill. Each Claude session is automatically exported as markdown, enabling: Searchable conversation history. Token reduction (up to 60 %+ in some benchmarks). Semantic search via Ollama embeddings. Drawbacks: higher setup cost, need to maintain recall schedules and folder structure. Cleaning File‑Chaos in an Existing Vault Step 1 – Exclude Directories via app.json <code>{ "userIgnoreFilters": [ "node_modules/", ".next/", "dist/", ".git/", ".vercel/", "public/" ] }</code> Step 2 – Regex Exclude File Types <code>/.*\.png/ /.*\.jpg/ /.*\.jpeg/ /.*\.svg/ /.*\.gif/ /.*\.ico/ /.*\.webp/ /.*\.js/ /.*\.ts/ /.*\.tsx/ /.*\.jsx/ /.*\.css/ /.*\.json/ /.*\.lock/</code> These rules perform a soft hide; files remain indexed. Step 3 – Hard Filter with File Explorer++ Install File Explorer++ (GitHub: https://github.com/kelszo/obsidian-file-explorer-plus) to apply wildcard or regex filters that can be toggled on the fly. Step 4 – Disable “Detect All File Extensions” Turn off this setting so that files such as .js , .ts , .json no longer appear in the file list. Step 5 – Optional File Ignore Plugin For a more permanent solution, use the File Ignore plugin (URL: https://obsidian-file-ignore.kkuk.dev/). It respects .gitignore -style rules and can rename files to keep them out of the index. Obsidian CLI Breakthrough Obsidian 1.12 introduced a CLI that lets tools such as Claude Code, Codex, and Gemini query the vault index directly instead of grepping files. In a benchmark on a 4 000‑file, 16 GB repository: Isolated‑note lookup dropped from ~10 s to <1 s (≈50× speed‑up). Full‑vault search also accelerated noticeably. Access method comparison: Obsidian CLI – fastest, most token‑efficient. REST API (community plugins) – flexible but adds an extra call layer. File system (grep / glob) – slowest and most token‑heavy. Obsidian is also adding first‑class Claude skills for editing .md and canvas files. Community Best Practice AI reads, humans write. Store only your own thoughts in the vault; keep Claude‑generated output (plans, memories, sessions) under ~/.claude/ . This preserves the vault as a true “second brain”. Example custom commands: /my-world – load the entire vault context. /today – start a daily plan from the daily note. /close – summarize and reflect on the day. /trace – trace the evolution of an idea. /ghost – answer in your voice using existing content. Plugin Recommendations File Explorer++ – wildcard/regex file hiding (e.g., *.js , *.png ). Dataview – cross‑vault queries on CLAUDE.md (project status tables, plan listings). Templater – generate uniform CLAUDE.md structures. Claudian , Agent Client , Claude Sidebar – UI integrations for chatting with Claude inside Obsidian. obsidian-claude-code-mcp and Claudesidian MCP – remote‑access bridges. Folder Note , File Hider , Hide Folders – auxiliary utilities for folder notes and selective hiding. Dataview Query Techniques Add frontmatter to each CLAUDE.md to enable structured queries. Example frontmatter: <code>--- type: claude-config project: my-app stack: [nextjs, tailwind, supabase] status: active ---</code> Query all project configurations: <code>```dataview TABLE project, stack, status FROM "" WHERE type = "claude-config" SORT project ASC ```</code> List all Claude plans sorted by last modification: <code>```dataview TABLE file.mtime as "Last Modified" FROM "claude-global/plans" SORT file.mtime DESC ```</code> Generate a templated CLAUDE.md with Templater: <code>--- 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 ## Technical Stack - ## Code Quality - ## Key Architecture - ## Environment Variables - </code> Obsidian CLI Performance Details Obsidian 1.12’s CLI lets AI tools query the vault index directly, eliminating the need for costly grep‑style scans. Benchmarks (reported by developers on X) show: Isolated note lookup: ~10 s → <1 s (≈50× faster). Full‑vault search: noticeable speed‑up. Comparison of access methods (see above) reinforces that the CLI is the most efficient path for token‑limited models. References (plain URLs) ballred/obsidian-claude-pkm – https://github.com/ballred/obsidian-claude-pkm Noah Vincent – IPARAG structure – https://noahvnct.substack.com/p/how-to-build-your-ai-second-brain obsidian-claude-code-mcp – https://github.com/iansinnott/obsidian-claude-code-mcp Claudesidian MCP – https://github.com/ProfSynapse/claudesidian-mcp QMD – https://github.com/tobi/qmd File Explorer++ – https://github.com/kelszo/obsidian-file-explorer-plus File Ignore – https://obsidian-file-ignore.kkuk.dev/ Dataview – https://github.com/blacksmithgu/obsidian-dataview Templater – https://www.obsidianstats.com/plugins/templater-obsidian Claudian – https://github.com/YishenTu/claudian Agent Client – https://github.com/RAIT-09/obsidian-agent-client Claude Sidebar – https://github.com/derek-larson14/obsidian-claude-sidebar Folder Note – https://lostpaul.github.io/obsidian-folder-notes/ File Hider – https://github.com/Eldritch-Oliver/file-hider Hide Folders – https://github.com/JonasDoesThings/obsidian-hide-folders