Claude Code + Obsidian: The Complete Setup Guide
How to point Claude Code at your Obsidian vault, write a CLAUDE.md for it, fence off folders, and build vault skills.

An Obsidian vault is a folder of Markdown files, and Claude Code is an agent built to work in folders of files. To connect them, open a terminal in your vault and run claude: no importer, no plugin, no API.
The rest is what makes it hold up: a CLAUDE.md, folders the agent can't touch, skills, an optional MCP bridge, and the limits.
How do you connect Claude Code to an Obsidian vault?
cd into your vault folder and run claude. Claude Code treats the vault like any codebase: it can open a daily note, follow a [[wikilink]], grep years of notes for a phrase, and write a new file into the right folder, all without you pasting anything into a chat.
If Claude Code isn't installed yet, the native installer is one command on macOS, Linux or WSL, and needs no Node.js (Claude Code docs):
curl -fsSL https://claude.ai/install.sh | bash
cd ~/path/to/your-vault
claude
Can you run Claude Code inside Obsidian?
Yes, through a plugin that embeds the CLI in a sidebar. Claudian runs Claude Code, Codex, OpenCode and other agents with your vault as the working directory, plus inline edits with word-level diffs. Agent Client does the same over the Agent Client Protocol, and Copilot for Obsidian added Claude Code support in version 4. Claudian alone has about 2.5 million downloads, per Obsidian's community plugin stats (October 2026). All three run agents on desktop only. Obsidian AI Plugins: The 7 Best in 2026, Compared puts them side by side.
What should go in your vault's CLAUDE.md?
The rules the agent should never have to hear twice. Claude Code reads CLAUDE.md at the start of every session, and a vault's file covers different ground from a code project's:
- Link syntax. Internal references use
[[wikilinks]], not Markdown links. It's the instruction most setups forget, and the reason an agent's new notes end up orphaned from your graph. - Naming and frontmatter. Date format for daily notes, title case, how tags and properties look. Consistent frontmatter (type, project, status, date) lets the agent filter notes without reading every file.
- Folder ownership. Which folders you write by hand, which the agent maintains, and which it never opens.
- What to ignore. Templates, attachments, archives.
Keep it short. Anthropic's docs set a target of under 200 lines per CLAUDE.md, because longer files use more context and reduce adherence (Claude Code docs). Run /doctor to have Claude propose cuts, and /doctor prompt-audit to find instructions that contradict each other.
Write the core of it yourself. ETH Zurich researchers found that context files generated by an LLM slightly lowered coding-agent success and raised inference cost by about 20%, while developer-written files did better than generated ones, though their gain over having no file at all was marginal (Gloaguen et al., 2026). /init gives you a draft; cut everything the agent could work out on its own. More on the file itself in CLAUDE.md: What It Is, Best Practices & Examples.
How do you keep Claude Code out of certain folders?
Use deny rules, not just instructions. CLAUDE.md is guidance Claude follows most of the time; Anthropic's docs say to enforce hard limits with permissions. Add Read and Edit rules to .claude/settings.json in the vault:
{
"permissions": {
"deny": ["Read(./archive/**)", "Edit(./inbox/**)"]
}
}
Here the agent can read your inbox but not edit it, and its file tools can't open the archive. One trap from older guides: a .claudeignore file does nothing, so move its entries into Read deny rules (Claude Code docs).
What folder structure works best?
A flat, boundaried one that separates what you write from what the agent maintains:
vault/
├── CLAUDE.md # root rules, read every session
├── .claude/
│ ├── settings.json # deny rules
│ └── skills/ # one folder per skill, each with a SKILL.md
├── inbox/ # raw capture: you write, 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
An agent given the whole vault with no boundaries will eventually "tidy" a note you were halfway through. One told to read inbox/ and write only to notes/ and projects/ stays useful and out of your way. For folder-specific rules, put a nested CLAUDE.md in that folder; Claude Code loads it once the agent reads or edits a file there.
How do you build custom vault commands?
Create a skill: a folder in .claude/skills/ containing a SKILL.md with frontmatter and instructions. The folder name becomes the command, so .claude/skills/link-orphans/SKILL.md gives you /link-orphans, and the description tells Claude when to load it on its own (Claude Code docs).
---
description: Finds notes with no links and proposes wikilinks. Use when asked to connect orphan notes.
---
Scan notes/ for files with no inbound or outbound [[wikilinks]].
For each, suggest up to three links to existing notes and explain why.
Write nothing until I approve the list.
Skills worth building first:
- Categorize inbox. File each note in
inbox/into the right folder and tag it from your taxonomy. - Link orphans. The example above.
- Daily note. Create today's note from your template and carry over yesterday's unfinished tasks.
- Meeting extraction. Pull the action items assigned to you out of a meeting note.
- Weekly review. Summarize the week's daily notes, what got done and what didn't, and draft next week's priorities.
If other agents use the vault too, an AGENTS.md works as the root file: Claude Code reads it when there's no CLAUDE.md, and it's used by more than 60,000 open-source projects (agents.md).
Should you add an Obsidian MCP server?
Add one when you want Obsidian-aware tools instead of raw file access. The Local REST API with MCP plugin, with about 810,000 downloads, runs an MCP server inside Obsidian that can patch a single heading or frontmatter key, search by frontmatter and tags, and run Obsidian commands. Register it with Claude Code using the API key from the plugin's settings:
claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
--header "Authorization: Bearer <your-api-key>"
Obsidian has to be running for it to answer, and for most vaults direct file access is enough. Obsidian MCP: How to Connect Your Vault to Any AI Tool covers the options.
Can Claude Code maintain your vault unattended?
Yes, with a review step. Claude Code's non-interactive mode runs a skill from a script, and --permission-mode acceptEdits lets it write files without stopping to ask (Claude Code docs); your deny rules still hold. Put the vault under Git first so every change is a diff you can read or revert in the morning:
claude -p "/categorize-inbox" --permission-mode acceptEdits
Because the agent rewrites sources into new notes, a misreading can get filed as fact and spread through the notes it links, so read the diffs and run an occasional audit.
What are the real limits?
The agent runs on your desktop, and the context stays in Claude Code. The CLI runs on macOS, Windows and Linux, and the plugins that run agents inside Obsidian are desktop-only, so on your phone you capture and at your desk you run the agent.
The deeper limit is what the vault is for. A Claude Code and Obsidian setup is a knowledge base: it answers "what do I know about this topic?" It doesn't tell ChatGPT in your browser or Cursor in your editor who you are and what you're working on, and it's still a vault you maintain. Obsidian for AI Context vs a Dedicated Context Layer covers where each one stops.
Where does personal context fit?
Next to the vault. An agent that knows every note still opens each session without your role, this week's priorities, or the decision that changed in yesterday's Slack thread, because none of that is in the vault, and the vault doesn't travel past Claude Code.
Unabyss carries that layer. It builds your personal context from Gmail, Google Calendar, Notion, Slack and your vault (through the Unabyss Obsidian plugin), and serves it over MCP to Claude Code, Claude, ChatGPT and Cursor. The agent working your vault then knows who it's working for from the first message.