obsidian-claude-integration

name	obsidian-claude-integration
description	Comprehensive guide for integrating Obsidian vaults as AI-powered second brains with Claude Code. Covers MCP integration, vault manifests, self-evolving patterns, auto-linking, and knowledge graph automation. Use when setting up Claude Code + Obsidian workflows, implementing bidirectional sync, creating CLAUDE.md manifests, or building self-healing knowledge systems.

Obsidian Second Brain + Claude Code Integration

Overview

Transform your Obsidian vault into an AI-powered second brain by integrating it with Claude Code. This skill covers multiple integration patterns from minimal setup to advanced self-evolving systems.

Key Insight: An Obsidian vault is essentially a codebase of markdown files. Claude Code is already excellent at navigating file structures and making surgical edits - no special plugin required.

Integration Patterns

Decision Tree

What integration level do you need?
├── Minimal (just works)?
│   └── Pattern A: Direct Access
│       └── Claude Code reads vault directly (no setup needed)
├── Enhanced discovery?
│   └── Pattern B: Manifest-Based
│       └── Add CLAUDE.md to vault root
├── Real-time bidirectional?
│   └── Pattern C: MCP Plugin
│       └── Install obsidian-claude-code-mcp
├── Self-evolving PKM?
│   └── Pattern D: COG Pattern
│       └── Git + automation + self-healing refs
└── Pre-configured structure?
    └── Pattern E: Claudesidian
        └── Adopt opinionated vault structure

Pattern A: Direct Access (Zero Setup)

Claude Code can already read and edit your vault. No configuration needed.

How It Works

# Claude Code navigates your vault like any codebase
cd /path/to/your/vault
claude

# Example interactions:
# "Read my daily note from today"
# "Find all notes mentioning project X"
# "Add backlinks to people mentioned in this note"

Best Practices

• Open Claude Code from vault root directory
• Use natural language to describe what you want
• Reference files by name or topic, not exact paths

Use Cases

Task	Claude Code Capability
Read notes	Direct file access
Edit notes	Surgical markdown edits
Add backlinks	Find references, insert wikilinks
Create notes	Write new files with proper frontmatter
Search content	Grep across all markdown files
Refactor structure	Move files, update references

Pattern B: Manifest-Based (CLAUDE.md)

Add a project manifest to help Claude Code understand your vault's structure and conventions.

CLAUDE.md Template

Create CLAUDE.md at your vault root:

# Obsidian Vault Manifest

## Vault Overview
This is a personal knowledge management vault using [describe your system].

## Folder Structure
- `00 - Inbox/` - Quick capture, unsorted notes
- `01 - Projects/` - Active project notes
- `02 - Areas/` - Ongoing responsibilities
- `03 - Resources/` - Reference materials
- `04 - Archive/` - Completed/inactive content
- `Daily/` - Daily notes (YYYY/MM/DD.md format)
- `Templates/` - Note templates

## Conventions
- Frontmatter: Always include `created`, `updated`, `tags`
- Links: Use `[[wikilinks]]` not markdown links
- Tags: Hierarchical (e.g., `#project/client-name`)
- Dates: ISO 8601 format (YYYY-MM-DD)

## Important Files
- `_index.md` - Main dashboard/MOC
- `project-context.md` - Current project context

## When Creating Notes
1. Always add proper frontmatter
2. Include backlinks to related notes
3. Tag appropriately for discoverability
4. Place in correct folder based on type

## When Editing Notes
1. Update the `updated` timestamp
2. Maintain existing link structure
3. Preserve block references (^block-id)

See: templates/CLAUDE.md for full template.

Pattern C: MCP Plugin Integration

Real-time bidirectional communication via Model Context Protocol.

Installation

# Install the MCP plugin from Obsidian Community Plugins
# Plugin: obsidian-claude-code-mcp
# Repository: github.com/iansinnott/obsidian-claude-code-mcp

Configuration

1. Enable plugin in Obsidian
2. Default WebSocket port: 22360
3. Claude Code auto-discovers running Obsidian instances

MCP Capabilities

Capability	Description
read_note	Read note content with metadata
write_note	Create or update notes
search	Semantic search across vault
list_notes	Browse vault structure
get_backlinks	Find notes linking to a file
get_outlinks	Find notes a file links to
get_tags	List all tags in vault

Claude Code MCP Configuration

Add to your Claude Code settings if not auto-discovered:

{
  "mcpServers": {
    "obsidian": {
      "transport": "websocket",
      "url": "ws://localhost:22360"
    }
  }
}

Pattern D: COG Self-Evolving Pattern

Git-based self-evolving second brain with auto-organization.

Architecture

vault/
├── .git/                    # Version control
├── CLAUDE.md                # AI manifest
├── _meta/
│   ├── patterns.md          # Learned patterns
│   ├── conventions.md       # Auto-discovered rules
│   └── maintenance-log.md   # Self-healing log
├── notes/                   # Content
└── daily/                   # Journal

Self-Healing Features

1. Auto cross-references: Updates links when notes are moved
2. Pattern learning: Discovers and applies your conventions
3. Orphan detection: Identifies unlinked notes
4. Consistency checks: Validates frontmatter, tags

Git Hooks Setup

# .git/hooks/post-commit
#!/bin/bash
# Trigger Claude Code maintenance after commits

claude --print "Check for broken links and orphan notes in the vault.
Fix any issues and update _meta/maintenance-log.md with actions taken."

Maintenance Commands

# Ask Claude Code to perform maintenance
claude "Analyze my vault for orphan notes and suggest connections"
claude "Find notes without proper frontmatter and fix them"
claude "Update all daily notes with missing navigation links"

Pattern E: Claudesidian Structure

Adopt a pre-configured vault structure optimized for AI interaction.

Folder Structure

vault/
├── CLAUDE.md                # Manifest (required)
├── Inbox/                   # Quick capture
├── Projects/                # Active work
├── Knowledge/               # Permanent notes
├── Journal/                 # Daily reflection
├── Templates/               # Note templates
└── _meta/                   # System files
    ├── prompts/             # Saved prompts
    ├── contexts/            # Context files
    └── exports/             # Generated outputs

Key Conventions

• Every note has frontmatter with id, created, updated
• Tags follow hierarchy: #type/subtype
• Daily notes link to previous/next
• Templates include Claude Code prompts

Common Workflows

Auto-Linking People, Places, Books

User: "Read my journal entry from today and add backlinks to all
people, places, and books mentioned"

Claude Code:
1. Reads today's daily note
2. Extracts entity mentions
3. Searches vault for existing notes
4. Creates new notes if needed
5. Inserts [[wikilinks]] throughout

Knowledge Graph Maintenance

User: "Find orphan notes and suggest connections"

Claude Code:
1. Identifies notes with no incoming/outgoing links
2. Analyzes content for potential connections
3. Suggests or creates links
4. Updates MOCs (Maps of Content)

Research Synthesis

User: "Synthesize all my notes on [topic] into a summary note"

Claude Code:
1. Searches for relevant notes
2. Extracts key insights
3. Creates structured summary
4. Links back to source notes

Daily Note Enhancement

User: "Review today's note and add structure"

Claude Code:
1. Reads raw capture
2. Adds proper frontmatter
3. Identifies tasks → adds checkboxes
4. Identifies mentions → adds links
5. Suggests tags based on content

Best Practices

For All Patterns

1. Keep vault in version control - Git enables rollback and change tracking
2. Use consistent frontmatter - Helps Claude Code understand note types
3. Maintain a manifest - CLAUDE.md provides context and conventions
4. Regular maintenance - Ask Claude Code to check for issues periodically

For MCP Integration

1. Keep Obsidian running - MCP requires active connection
2. Use semantic search - Leverage MCP's search capabilities
3. Handle conflicts - Be aware of simultaneous edits

For Self-Evolving Systems

1. Review AI changes - Check git diff before committing
2. Train on preferences - Correct mistakes to improve patterns
3. Document exceptions - Update manifest with edge cases

Troubleshooting

Claude Code Not Finding Notes

# Ensure you're in the vault directory
pwd  # Should show vault path

# Check file permissions
ls -la *.md

# Verify markdown extension
find . -name "*.md" | head -20

MCP Connection Failed

# Check Obsidian is running
pgrep -l Obsidian

# Verify plugin is enabled
# Settings → Community Plugins → obsidian-claude-code-mcp

# Check port availability
lsof -i :22360

# Test WebSocket connection
websocat ws://localhost:22360

Broken Wikilinks After Edits

# Ask Claude Code to fix
claude "Find all broken wikilinks in the vault and fix them"

# Or use grep to find issues
grep -r "\[\[" --include="*.md" | grep -v "\.obsidian"

Integration Comparison

Feature	Direct	Manifest	MCP	COG	Claudesidian
Setup Required	None	Minimal	Plugin	Git + hooks	Structure
Real-time Sync	No	No	Yes	No	No
Semantic Search	Basic	Basic	Yes	Basic	Basic
Self-Healing	No	No	No	Yes	Partial
Vendor Lock-in	None	None	Low	None	Structure
Best For	Simple	Organized	Power users	Automation	New vaults

Resources

References

• references/mcp-integration.md - MCP protocol details
• references/cog-pattern.md - Self-evolving architecture
• references/workflows.md - Common automation workflows

Templates

• templates/CLAUDE.md - Vault manifest template
• templates/daily-note.md - AI-friendly daily note
• templates/project-note.md - Project note template

External Resources

• obsidian-claude-code-mcp - MCP Plugin
• COG-second-brain - Self-evolving pattern
• Claudesidian - Pre-configured vault
• minimal-second-brain - Minimal template

Quick Start

Fastest Path (Pattern A + B)

# 1. Navigate to your vault
cd /path/to/your/obsidian/vault

# 2. Create a minimal manifest
cat > CLAUDE.md << 'EOF'
# Vault Manifest

This is my Obsidian vault. Key conventions:
- Daily notes in `Daily/YYYY/MM/DD.md`
- Use `[[wikilinks]]` for internal links
- Frontmatter with `created`, `updated`, `tags`
EOF

# 3. Start using Claude Code
claude "What notes do I have about [topic]?"

Full Integration (Pattern C)

1. Install obsidian-claude-code-mcp plugin
2. Create CLAUDE.md manifest
3. Enable plugin in Obsidian settings
4. Claude Code auto-connects via WebSocket

Self-Evolving Setup (Pattern D)

1. Initialize git in vault
2. Create CLAUDE.md manifest
3. Add git hooks for maintenance
4. Schedule periodic Claude Code reviews

---

Gotchas

• Vault paths with spaces break raw bash heredoc without quoting — always "$VAULT" (with quotes) when constructing paths. A space silently splits the path arg into two.
• MCP server lifecycle: a crashed server stays in transition state for ~30s before retry — claude won't show an error during the gap; it just waits.
• Frontmatter append from Claude can duplicate keys silently — YAML allows duplicate keys; Obsidian shows the last; some plugins read the first. Always edit-in-place via a parser, not blind append.
• CLAUDE.md manifests under the vault root vs under .obsidian/ — the vault-root one is visible to humans; the .obsidian/ one survives folder reorganization but is hidden.
• MCP file-system tools obey vault sandbox, but raw Bash does not — easy accidental escape via shell commands; document the boundary explicitly per skill.