julianobarbosa/obsidian-claude-integration

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.