Most people use Obsidian as a second brain. Most people use Claude as a chat interface. Running them together changes both of those things into something that actually compounds.
This is the setup I've been running for several months. It's not a plugin. It doesn't require an API dashboard. It runs entirely from the terminal, touches your vault directly, and produces output you can actually trust inside your notes because you control the prompt, the context, and where the output lands.
Here's how it works.
Why Claude Code and Not the Web UI
The Claude.ai chat interface is fine for isolated queries. You ask something, you get something back, you copy it into whatever document you're working in. The loop is slow and stateless — every conversation starts from zero unless you're managing memory manually.
Claude Code is a CLI tool. You install it, you point it at a directory, and it operates with awareness of everything in that context. That changes what's possible. Instead of describing your vault structure to a chat window, the model reads it. Instead of pasting chunks of notes to get a synthesis, you give it a path and a task.
The install is straightforward:
$ npm install -g @anthropic-ai/claude-code
$ claude --version
Once it's on your PATH, you can invoke it from inside any directory. That includes your Obsidian vault.
The Vault Setup
The vault itself needs minimal configuration to work well with Claude Code. The key constraint is that Claude Code operates on the working directory — so you run it from your vault root and it sees the file tree from there.
A few structural decisions that make this cleaner:
Flatten where possible. Claude Code can traverse subdirectories, but deep nesting means more tokens burned on path resolution and less room for actual note content in the context window. If your vault looks like Projects/Active/Q1/Research/Sources/topic.md, that's four folders of indirection. Research/topic.md costs less to work with.
Keep your attachments isolated. Images, PDFs, and media files that Claude Code can't process should live in a dedicated folder. A top-level _attachments/ directory works. This prevents the tool from indexing binary files that add nothing to context.
Name files like sentences. Obsidian's backlink system works on filenames. Claude Code reads those same filenames as context signals. A note called CAN-bus-traffic-without-DBC.md gives the model usable information before it reads a single line. A note called untitled-48.md gives it nothing.
The directory structure I use:
vault/
_attachments/
_templates/
Projects/
Areas/
Resources/
Archive/
CLAUDE.md
That last file is where most of the setup value lives.
CLAUDE.md as Your Thinking Manifest
Claude Code reads a file called CLAUDE.md at the root of any project directory as a persistent context document. It loads automatically on every session. This is the mechanism that removes the stateless problem entirely.
Your CLAUDE.md is not documentation for other humans. Write it for the model.
Mine contains:
- A short description of what this vault is for and how I think about it
- The naming conventions and folder logic
- Recurring project contexts with their current status
- Active questions I'm working through
- Output preferences — how I want notes formatted, what headers mean, what tags I use
A minimal starting version:
# Vault Context
This vault is a working knowledge base for security research, hardware projects,
and long-form writing. Notes are written in Obsidian-flavored Markdown.
## Structure
- Projects/ — active work with deadlines or deliverables
- Areas/ — ongoing domains (e.g., ESP32, OSINT, writing)
- Resources/ — reference notes, evergreen content
- Archive/ — completed or paused work
## Conventions
- Tags use #category/subcategory format
- MOC notes are named with the prefix "MOC — "
- Source notes include a frontmatter `source:` field
## Active Context
- Currently working on: [update this manually before sessions]
- Open questions: [list the things you're stuck on]
The "Active Context" section is where the leverage is. Before a working session, I update it with whatever I'm actually thinking about. Two lines, sometimes three. Claude Code reads it on every invocation and that information colors every response in the session.
This is the part people skip. Don't skip it.
The Workflows That Actually Stuck
A lot of AI-in-PKM workflows look good in demos and collapse in practice. These are the ones that became permanent.
Note synthesis. I collect notes in a topic area over weeks, then ask Claude Code to synthesize them into a single reference note. The command looks like:
$ claude "Read all notes in Resources/CAN-bus/ and write a synthesis note
that surfaces the non-obvious connections. Output it as Markdown,
first-person, under 600 words. Do not include anything I didn't write."
The constraint at the end matters. Without it, the model interpolates from its own training data and pollutes the synthesis with things you never actually noted. That clause keeps the output honest.
Gap analysis. When I'm building out a topic area and want to know what's missing:
$ claude "Look at everything in Areas/OSINT/ and tell me what topics
a practitioner would expect to find here that aren't covered.
Give me a list, not prose."
This surfaces the blind spots faster than reading through the vault manually. The model doesn't know what you don't know, but it knows what's normal coverage for a given domain — and it can diff that against your actual notes.
Backlink suggestion. Obsidian's graph view shows what's connected, but it doesn't tell you what should be connected. The model can:
$ claude "Read Resources/firmware-extraction.md and suggest five
existing notes in this vault it should link to, with one sentence
explaining why each connection is meaningful."
You review the suggestions and add the links manually. Takes 90 seconds and your graph gets denser without the note content getting padded.
Draft expansion. I keep a lot of rough notes — fragments, half-formed arguments, unfinished research. For anything I want to turn into a full note or a piece of writing, I use:
$ claude "Expand Projects/draft-can-inference.md into a complete note.
Keep my voice, don't add claims I didn't make, fill in technical detail
where it's consistent with what I've already written."
The --print flag produces non-interactive output you can redirect straight into a file:
$ claude --print "Summarize Resources/RFID/ in 200 words" > Resources/RFID-summary.md
That file lands directly in your vault and Obsidian picks it up immediately.
Where This Breaks
Context window limits are a real ceiling. If your vault has thousands of notes, Claude Code is not reading all of them — it's sampling based on recency and relevance signals. Large vaults need more deliberate scoping. Run commands with explicit paths, not vault-wide sweeps.
The model will hallucinate connections between notes if you ask synthesis questions without constraining the output to what you've actually written. The "do not include anything I didn't write" constraint is not optional.
CLAUDE.md drift is a real problem. If you write it once and never update the Active Context section, the document becomes stale noise. The model reads it as current, you get responses calibrated to a version of your work that no longer exists. Five minutes of maintenance before each session prevents this.
Claude Code also does not write to files without explicit instruction — which is a feature, not a gap. It's not going to touch your vault without you telling it to. All writes should be deliberate and reviewed before committing.
The Part Nobody Talks About
The productivity lift from this setup is real, but the more interesting effect is structural. When you know the model can read your vault, you write notes differently. You name things more precisely. You surface connections explicitly instead of relying on memory to bridge them later. The vault becomes less of a dump and more of a working document — something you write for an intelligent reader who will actually use it.
That shift in how you approach note-taking compounds over time in ways that don't have anything to do with AI. The setup teaches better thinking habits by creating a reader worth writing for.
The full configuration guide, including CLAUDE.md templates, scoped workflow prompts, and vault structuring patterns that hold up past 1,000 notes, is at numbpilled.gumroad.com/l/obsidian-claude.
Top comments (0)