tools-only 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
- Enable plugin in Obsidian
- Default WebSocket port: 22360
- 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
- Auto cross-references: Updates links when notes are moved
- Pattern learning: Discovers and applies your conventions
- Orphan detection: Identifies unlinked notes
- 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
- Keep vault in version control - Git enables rollback and change tracking
- Use consistent frontmatter - Helps Claude Code understand note types
- Maintain a manifest - CLAUDE.md provides context and conventions
- Regular maintenance - Ask Claude Code to check for issues periodically
For MCP Integration
- Keep Obsidian running - MCP requires active connection
- Use semantic search - Leverage MCP's search capabilities
- Handle conflicts - Be aware of simultaneous edits
For Self-Evolving Systems
- Review AI changes - Check git diff before committing
- Train on preferences - Correct mistakes to improve patterns
- 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)
- Install obsidian-claude-code-mcp plugin
- Create CLAUDE.md manifest
- Enable plugin in Obsidian settings
- Claude Code auto-connects via WebSocket
Self-Evolving Setup (Pattern D)
- Initialize git in vault
- Create CLAUDE.md manifest
- Add git hooks for maintenance
- Schedule periodic Claude Code reviews