Obsidian + Claude Code: The Complete Setup Guide
Your Obsidian vault is a folder of Markdown files on disk. Claude Code is an agent that reads, writes, and searches...
Your Obsidian vault is a folder of Markdown files on disk. Claude Code is an agent that reads, writes, and searches folders of files. Point one at the other and your notes stop being a passive archive — they become something an agent can reorganize, cross-link, and extend while you sleep.
Most of what's written about this setup is a YouTube walkthrough or a five-minute Medium demo. This is the text version people keep asking for: how to open the vault, how to write a CLAUDE.md that actually shapes behavior, a folder structure that holds up, the overnight workflows worth stealing, and the one hard limit nobody mentions until you hit it.
How do you connect Claude Code to an Obsidian vault?
Open a terminal, cd into your vault folder, and run claude. That's the whole connection. There's no importer and no plugin required for the core setup —
running the Claude Code CLI inside an Obsidian vault folder gives the agent full read, write, edit, and search access to all local markdown files and vault subdirectories.
Because a vault is just plain Markdown in a directory, the agent treats it like any codebase. It can open a daily note, follow a [[wikilink]] to a related page, grep across years of notes for a phrase, and write a new file into the right folder — all without you copying anything into a chat window.
If you'd rather not live in the terminal, a plugin bridges the CLI into Obsidian's interface. Claudian is an Obsidian plugin that embeds Claude Code, Codex, and other local agents as AI collaborators in your vault, making the vault the agent's working directory. You get a sidebar chat, inline edits with diff previews, and the agent working against the same files you're editing. Obsidian itself is a big enough base for this to matter — the tool has an estimated 1M–1.5M+ users as of 2025 according to Fueler's Obsidian statistics report, most of them storing everything as local files.
What should go in your vault's CLAUDE.md?
The rules the agent should never have to be told twice. Global agent rules and vault conventions are configured using a CLAUDE.md file placed at the root of the vault, which instructs the model to apply syntax like double bracket wikilinks and follow specific file naming conventions. Claude Code reads it automatically at the start of every session, so it's the difference between an agent that respects your system and one that invents its own.
A vault CLAUDE.md is not a code project's CLAUDE.md. Cover these:
- Link syntax. State that internal references use
[[wikilinks]], not Markdown links. This is the single instruction most setups forget, and it's why an agent's new notes end up orphaned from your graph. - Naming conventions. Date format for daily notes, title case rules, how tags and frontmatter should look.
- Folder boundaries. Which directories the agent may write to, and which are off-limits (more on this below).
- Human vs. agent separation. Name the folders you write by hand versus the ones the agent maintains, so it never rewrites your raw thinking.
Keep it tight. Per Anthropic's Claude Code memory documentation, longer memory files still load in full but instruction adherence drops as they grow — and newer versions ship a /doctor check that flags a CLAUDE.md that's outgrown its usefulness. Treat ~150–200 lines as a ceiling, not a target: the system prompt already consumes part of the instruction budget, leaving room for roughly 100–150 of your own before the model starts dropping rules.
There's a good reason to hand-write this file rather than auto-generate it. A 2024 study of context files (Antropian et al., referenced across the AGENTS.md ecosystem) found human-written instructions improved agent performance while auto-generated ones sometimes hurt it. The root file is worth your ten minutes.
What folder structure works best?
A flat, boundaried structure the agent can navigate without guessing. The goal is a clear line between what you write and what the agent maintains.
A structure that holds up:
vault/
├── CLAUDE.md # root rules — read every session
├── .claude/
│ └── skills/ # custom commands (see below)
├── inbox/ # raw capture — human-written, agent reads only
├── notes/ # permanent notes — agent may create and link
├── daily/ # daily notes — agent appends, never rewrites
├── projects/ # active work — agent maintains
└── archive/ # off-limits to the agent
The principle underneath it: isolate the folders the agent owns from the folders you own. Say so explicitly in CLAUDE.md. An agent given the whole vault with no boundaries will eventually "tidy" a note you were mid-thought on. One told to read inbox/ but only write to notes/ and projects/ stays useful and stays out of your way. You can also drop a nested CLAUDE.md inside a subfolder for rules specific to that directory — Anthropic's memory docs note that nested files load when the agent reads from that folder.
How do you build custom vault commands?
Put a skill file in .claude/skills and it becomes a repeatable command.
Custom slash commands and automated workflows are created by placing modular skill files inside the .claude/skills directory, allowing users to trigger vault-wide note categorization and link graph generation.
Each skill is a Markdown file with frontmatter describing what it does and when to use it.
Skills worth building first:
- Categorize inbox. Read everything in
inbox/, file each note into the right folder, apply tags from your taxonomy. - Link orphans. Scan for notes with no inbound or outbound links and propose
[[wikilinks]]to connect them into the graph. - Synthesize a topic. Gather every note touching a subject and produce one structured summary page.
This is the same convention the wider agent ecosystem standardized on. AGENTS.md has emerged as the de facto open standard for guiding AI coding assistants, adopted by over 20,000 repositories and formalized in August 2025 through collaboration between OpenAI, Google, and others. Your skills library is that idea pointed at a knowledge base instead of a repo.
The overnight-agent workflow people rave about
The setup that gets shared most: queue a batch job before bed, wake up to a reorganized vault. Because Claude Code can run a skill across every file unattended, you can tell it to process the day's captures, link new notes into the graph, and draft summaries — then review the diffs over coffee. Nothing hits your permanent notes without you seeing the change.
The honest caveat: because the agent summarizes your sources into new pages, a small misreading can get written in as fact and then propagate across the notes it links. It's the same failure mode as any agent-maintained knowledge base — worth a periodic audit, not a reason to avoid it.
What are the real limits?
It's desktop-only, and it's Claude Code-only. Claude Code execution relies on desktop Node.js runtime and terminal environments, limiting native agent operations to desktop operating systems and preventing native execution on mobile versions of Obsidian. Capture on your phone, run the agent at your desk.
The deeper limit is what the vault is for. A Claude Code + Obsidian setup is a knowledge base — it answers what do I know about this topic? It doesn't answer who am I and what am I working on in a way that follows you to Cursor, ChatGPT, or your next tool. That's personal context, and it lives in a different layer. The two are complementary: the vault holds your knowledge; personal context holds you. If you're weighing the vault as your context store, Obsidian for AI context vs. a dedicated context layer covers where each one stops.
Where personal context fits
An agent that knows your vault still doesn't know you. It can navigate every note and still open each session unaware of your role, your current project, or how you want things written — because that isn't in the vault, and even if it were, it wouldn't travel past Claude Code.
Unabyss serves that layer. It extracts your personal context from the sources where it already lives and delivers it to any MCP-compatible tool — Claude Code included — so the agent working your vault also knows who it's working for, from the first message. Memory is a side effect of one tool. Portable context is infrastructure across all of them.
See how personal context works →
