Obsidian + Claude Code: The Developer Second Brain I Actually Use

I've tried every note-taking app in the last six years. Notion, Roam, Logseq, Apple Notes, plain text files in Vim. They all worked for about three months before I abandoned them. Obsidian is the one that stuck. And when I connected it to Claude Code earlier this year, something clicked that I didn't expect.

This isn't a "here's why Obsidian is great" puff piece. I want to walk through the exact setup I use every day - the folder structure, the plugins, how Claude Code reads and writes to my vault, and why this combination replaced four other tools I was paying for.

Why Obsidian Won (For Me)

Obsidian is local-first Markdown. That's it. That's the entire pitch.

But that simplicity is why it works for developers. Your notes are files. They live on your disk. You can git init your vault and push it to a private repo. You can grep through them. You can pipe them into an LLM and get useful output back.

Try doing any of that with Notion. You can't. Your data lives in their database, behind their API. I used Notion for two years and the day I wanted to search my notes from the terminal, I realized I'd been renting my own knowledge.

With the 1.12 update, Obsidian added CLI support, Bases for structured data views, and made it free for commercial use. No more guilt about using it at work without buying the license.

The real reason it won: every piece of data I put in is available to every other tool on my machine. Including Claude Code. That changes everything.

My Vault Structure for Development Work

Spent a month trying different structures before this one. Used it for eight months without changing it.

vault/
  Projects/
    active/
      project-name/
        README.md
        decisions.md
        bugs.md
        architecture.md
    archived/
  Meetings/
    2026-03-25-standup.md
  Research/
    llm-comparison-notes.md
  Templates/
    project-kickoff.md
    meeting-note.md
    bug-report.md
  Daily/
    2026-03-25.md
  Scratchpad/

The Projects/active/ split matters. Archiving finished projects keeps search results clean. I don't want Claude Code finding notes about a project I abandoned in November.

The Scratchpad/ folder is for half-formed ideas. Every Friday I spend ten minutes moving items to the right folder or deleting them. Most get deleted.

Meeting notes use ISO date format because it makes sorting trivial and Templater generates it automatically. Each note gets a template with attendees, decisions, and action items. Three months in, this eliminated 90% of "what did we decide about X?" Slack messages.

The Plugin Stack That Actually Matters

1,800+ community plugins. Most are garbage. Here's what I keep installed.

Git plugin is non-negotiable. Auto-commit every 30 minutes, push on close. I've recovered from a corrupted file exactly once, took 45 seconds.

Dataview turns your vault into a queryable database. I have a dashboard that shows all projects with status, last modified, and open bugs. Replaced a Notion database I maintained by hand.

Templater can execute JavaScript, so my meeting note template auto-fills the date, creates the right folder path, and pulls attendees from a reference file. One of those 10x productivity moves that compounds.

AI Plugins: What Works and What Doesn't

Smart Connections is the standout. RAG against your entire vault. I asked "what were the performance issues for the payment service?" and it pulled three meeting notes and a bug report I forgot about. Uses local embeddings so notes never leave your machine for indexing. I use Claude Sonnet for generation. Covered my AI tool evaluation approach in the tools guide.

Copilot for Obsidian is decent. Chat interface, vault-wide Q&A. More polished than Smart Connections, less powerful for retrieval.

Text Generator and Nova are fine. Inline generation, summarization. Used them a month, realized I open Claude in a browser tab anyway.

Connecting Claude Code to Your Vault

This turned my vault from "nice note system" into something I rely on for development. Three ways to connect them.

Option 1: The MCP Server. The obsidian-claude-code-mcp package exposes your vault to Claude Code as a context source. Add it to your Claude Code config and Claude can read, search, and reference your notes while working on code.

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["-y", "obsidian-claude-code-mcp",
               "--vault-path", "/path/to/your/vault"],
      "env": {}
    }
  }
}

With this running, I tell Claude Code "check my project notes for the caching decision" and it finds the decision record, reads it, and applies that context to whatever code it's writing. No copy-pasting. No window switching.

Option 2: Agent Client Plugin. Interact with Claude Code from within Obsidian. More experimental. I tried it two weeks, went back to MCP because I prefer Claude Code in my terminal.

Option 3: Terminal Plugin. Simplest approach. Open terminal pane in Obsidian, run Claude Code from your vault directory. Zero config. This is how I started before the MCP server existed. Covered the full Claude Code setup separately.

The Developer Second Brain Pattern

The actual workflow. I call it capture-organize-process.

Capture. Everything goes into Obsidian first. Meeting notes, bug observations, architecture ideas, error messages. QuickAdd with a hotkey, under five seconds. If capturing takes more than a few seconds you'll stop doing it. Daily note is the inbox.

Organize. Every Friday. Move captures to the right folder. Add YAML frontmatter with tags and status. Link related notes. Twenty minutes. Most valuable twenty minutes of my week. Six months of organized notes created a searchable knowledge base no wiki has ever given me.

Process. Claude Code reads my decision records, architecture notes, bug history via MCP. When I ask it to implement caching, it already knows we chose Redis over Memcached from a decision record three months ago. It knows we rejected LRU from a January meeting note. This context separates an AI that writes generic code from one that writes code for your project.

Works because Obsidian stores Markdown, and LLMs are excellent at Markdown. Zero friction between "note I wrote for myself" and "context for my AI." Talked about this kind of workflow in my vibe coding piece.

The llms.txt Trick

Small thing, big impact.

I keep llms.txt in the root of each project folder in my vault. Structured summary - tech stack, conventions, decisions, pitfalls. Like a CLAUDE.md but for your notes.

# Project: Payment Service API

## Stack
- Node.js 22, TypeScript 5.6, Express, Prisma
- PostgreSQL 16, Redis 7 for caching

## Key Decisions
- Idempotency keys on all write endpoints
- Stripe webhooks via Bull queue
- No direct DB access from route handlers

## Known Issues
- Connection pool exhaustion over 500 req/s
- Webhook replay can cause duplicates

## Patterns
- Monetary amounts as integers (cents)
- Dates in UTC, convert at API boundary
- Error responses follow RFC 7807

When Claude Code connects via MCP, this gives it a fast summary without reading dozens of notes. Quality of suggestions went up after I started maintaining these.

Obsidian vs. Everything Else for Dev Notes

If you don't care about AI integration and love outliners, Logseq is solid. If your team uses Notion, keep it for team docs. But for a developer who wants notes feeding into Claude Code, version control on their knowledge base, and data on their own disk - Obsidian is the only option that checks every box.

Practical Tips from Eight Months of Use

Don't over-organize on day one. Just start writing. The structure becomes obvious after a month. I reorganized twice before the current setup stuck.

Frontmatter on everything. At least tags, created, status. This makes Dataview queries work. Without it your vault is a pile of files. Templater auto-fills this so it costs zero effort.

Link aggressively. Every time I mention a project, person, or decision, I [[link]] it. After three months, patterns emerge in the graph you didn't know existed.

Keep your vault under 10,000 notes. I archive ruthlessly. If a note hasn't been opened in six months, it goes to archive. Smaller vault means faster search, more relevant AI context, less noise.

Daily note is an inbox, not a journal. I tried journaling. Lasted a week. Now it's purely functional - tasks, links, quick captures. If something deserves a proper note, I write one.

Sync with Git, not Obsidian Sync. Free, better version history, integrates with your existing workflow. The Git plugin handles everything. If you're comfortable with Git (and you should be, it's foundational), use it.

A Real Workflow: Bug Investigation

Last week. Payment webhook handler processing events out of order. Customers seeing stale subscription statuses.

Step one: captured error messages and Datadog trace IDs in my daily note. Fifteen seconds.

Step two: created a bug report using my template. Templater auto-filled date, linked to project, set status to "investigating."

Step three: opened Claude Code, told it to check the webhook handler code AND my project notes for previous webhook issues. MCP found a January meeting note where we discussed the exact same ordering problem and decided to add sequence numbers. That decision was never implemented. Three months of context, found in ten seconds.

Step four: Claude Code wrote the fix referencing both the code and the decision record. Right on first attempt because it had the full context. I've written about this agentic workflow before.

Step five: updated bug report, linked to the meeting note, closed it. Alert to deployed fix: 40 minutes. Without vault context, I'd have spent an hour reading Slack history.

What I Stopped Using

Graph view as a daily tool. Looks cool in screenshots. I open it maybe once a month.

Complex Dataview dashboards. Built an elaborate one with eight queries. Slow, never looked at it. Now I have three queries: active projects, recent bugs, upcoming deadlines.

Obsidian for code snippets. Code belongs in your editor or local LLM setup where you can run it. Obsidian is for prose and context.

Canvas for architecture diagrams. Doesn't render on GitHub, not accessible via MCP. I use Mermaid in Markdown instead.

The pattern: cut anything that looks impressive but doesn't save time. The vault serves the work. Everything else is note-taking theater.

Frequently Asked Questions