Obsidian and Claude Code: 4 ways to set it up
Steven Liechtifounder of Koru
7 minute read
Short answer
The simplest way to use Claude Code with Obsidian is to open a terminal in your vault folder and run claude: your notes are plain Markdown files, so Claude Code can read, search and edit them directly, and Obsidian picks up the changes on its own. Add a CLAUDE.md that explains how your vault is organized, and you have most of what people mean by a "second brain" setup. Plugins and MCP servers are optional extras for running Claude inside the Obsidian window or giving it Obsidian-aware search.
This guide walks through the four common setups, what each one costs you, and an alternative if you'd rather run Claude Code in a tab next to your notes without plugins.
| Setup | What you install | Where Claude Code runs | Good for | Watch out for |
|---|---|---|---|---|
| 1. Terminal in the vault folder | Nothing beyond Claude Code | Your own terminal | Most people; full file and Git access | You switch between two windows |
| 2. CLAUDE.md and skills | Two kinds of text files | Your own terminal | Making Claude follow your vault's rules | Keep CLAUDE.md short |
| 3. Sidebar plugin (Claudian, Claude Sidebar) | A community plugin | A pane inside Obsidian | Staying in one window | Plugins run with full access to your computer |
| 4. MCP server | A plugin or a separate server | Terminal or a plugin | Obsidian-aware search, backlinks, commands | Another moving part to keep running |
The setups stack: start with 1 and 2, and add 3 or 4 when you need them.
An Obsidian vault is a folder of Markdown files on your disk. Obsidian's own help page says it "automatically refreshes your vault to keep up with any external changes" (How Obsidian stores data), so edits Claude Code makes show up in the app without a reload.
- Install Claude Code and sign in.
- Open a terminal and change into your vault:
cd ~/Documents/MyVault. - Run
claude. - Ask it something concrete, for example "find every note tagged #meeting from October and list the open action items".
Two habits make this safer. First, put the vault under Git (git init in the vault folder) so you can review and undo every change Claude makes. Second, tell Claude to leave the .obsidian folder alone, since it holds your settings and plugin code.
If your vault isn't in the folder you're working in, Claude Code's --add-dir flag gives it access. Note that the added folder's CLAUDE.md isn't loaded by default; the Claude Code memory docs explain how to turn that on with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.
Claude Code reads a CLAUDE.md file at the start of every session. Anthropic describes it as "the place you write down what you'd otherwise re-explain" and recommends keeping each file under 200 lines (Claude Code memory docs). Run /init inside the vault to get a starter file, then edit it.
A vault CLAUDE.md usually covers:
# Vault rules
- Daily notes live in `Journal/YYYY-MM-DD.md`. Project notes live in `Projects/<name>/`.
- Link related notes with [[wikilinks]], not Markdown links.
- Put tags in frontmatter as `tags: [meeting, client-x]`.
- Never edit files in `.obsidian/` or `Templates/`.
- When you create a note, add a link to it from the matching index note in `Maps/`.If your vault already has an AGENTS.md for other agents, Claude Code can read it in place of CLAUDE.md. We compared the two files in AGENTS.md vs CLAUDE.md.
Skills cover the jobs you repeat. A skill is a folder with a SKILL.md inside, saved in .claude/skills/<name>/ in the vault or in ~/.claude/skills/ for every project. Unlike CLAUDE.md, "a skill's body loads only when it's used", and custom slash commands have been merged into skills (Claude Code skills docs). Examples of vault skills: a weekly review that collects the past seven daily notes, an inbox triage that files loose notes into folders, and a "summarize this source into a literature note" routine.
If you want the vault to grow into a wiki the agent maintains for you, our post on the LLM wiki pattern goes further.
If switching between the terminal and Obsidian gets old, community plugins put the agent in an Obsidian pane. Two are popular as of November 5, 2026 (star counts from GitHub):
- Claudian (15,915 stars, MIT) embeds Claude Code, Codex, Grok Build, OpenCode and other agent CLIs in the vault, with the vault as the working directory. It needs Obsidian 1.13.0 or later and is desktop only. Its privacy section is clear that your input, attached files and tool outputs are sent to whichever provider you pick.
- Claude Sidebar (457 stars, MIT) opens a real terminal in the sidebar and runs Claude Code, Codex, Grok Build, OpenCode, Copilot, Cursor Agent or Pi in it. It needs Python 3, plus
pywinptyon Windows.
The trade-off is security, and Obsidian is upfront about it: it "cannot reliably restrict plugins to specific permissions or access levels", and plugins can read files on your computer, connect to the internet and install programs (Plugin security). A plugin that runs an AI agent sits at the top of that risk scale, so install one only from a repository you've looked at.
Claude Code can already read your files, so MCP isn't required. It earns its place when you want things only the running app knows: Obsidian's search index, backlinks, or the ability to run an Obsidian command.
You have three routes:
- The Local REST API plugin (coddingtonbear/obsidian-local-rest-api, 3,116 stars) exposes an MCP endpoint you add with
claude mcp add --transport http. - obsidian-claude-code-mcp (359 stars) runs a server inside Obsidian that Claude Code finds over WebSocket; you pick the vault with
/ide. Its last commit was June 2025 and it uses the older HTTP with SSE transport for other clients, so check it still works with your Obsidian version. - The Obsidian CLI isn't MCP, but Claude Code can call it from the shell. It needs the Obsidian 1.12.7 or later installer and the app running, and offers search with context, backlinks and orphan detection (Obsidian CLI).
We compared the Obsidian MCP servers, with setup commands for each, in Obsidian MCP servers vs a notes app with a built-in MCP server.
- You live in the terminal already: Setup 1 plus 2. No plugins, full Git history, nothing new to trust.
- You want one window: add Claudian or Claude Sidebar, after reading its code and README.
- You want Claude to use backlinks and Obsidian search: add the Obsidian CLI or an MCP server.
- You want the agent in a tab next to your notes, without plugins: read on.
Koru is a free, open source (MPL-2.0) notes app for Windows, macOS and Linux, built in native Rust rather than Electron and designed to work offline. It runs Claude Code next to your notes without a plugin, and it ships its own MCP server, koru-mcp, with every build.
- Terminal tabs. On a Mac, press + in the tab strip and choose Agents: Claude, OpenCode, Codex, Grok or Kimi open as tabs beside your documents, if they're installed. On Windows, open a shell tab and run
claudethere until agent tabs arrive in an upcoming release. - Built-in MCP. Koru's Welcome page has a Manage documents over MCP row that copies the exact command for your install. In Claude Code, run
claude mcp add koru --followed by that command (Claude Code MCP docs). Claude can then search, read and edit your Koru notes, and it can reach them even when the app is closed. - Sync. Peer-to-peer sync between your devices is free and end-to-end encrypted. Koru Cloud is optional at $9.99/month for 100GB.
Where Obsidian is better for this: an Obsidian vault is a folder of .md files, so Claude Code's own file tools and Git work on it directly. Koru keeps notes in its own local store, so Claude works through MCP instead, and that MCP server has no rename, move or delete tools. Koru also doesn't ask for approval per MCP client, so connect only tools you trust. There's no Koru phone app yet.
If you're moving a vault over, Koru imports Markdown files, though [[wikilinks]] come in as plain text. Our Obsidian alternative page covers the rest of the comparison, and Bring your own AI shows how agent tabs work.
Download Koru and open Claude Code in a terminal tab next to your notes.
No. Run `claude` from a terminal in your vault folder and it reads and edits your notes as files. Obsidian refreshes on its own when files change. Plugins only add a pane inside Obsidian or Obsidian-specific tools such as backlinks.
Not for reading and writing notes. MCP, or the Obsidian CLI, helps when you want Claude to use Obsidian's search, backlinks or commands, which only the running app knows about.
Your folder structure, naming rules, how you link and tag notes, and which folders to leave alone, such as `.obsidian` and templates. Anthropic recommends keeping it under 200 lines and moving longer procedures into skills.
A `SKILL.md` file in `.claude/skills/<name>/` inside your vault that describes a repeatable job, such as a weekly review. Claude loads it only when the job comes up, so long instructions don't cost context in every session.
Put the vault under Git so every change can be reviewed and undone, and keep Claude out of `.obsidian`. Be careful with plugins: Obsidian says it can't restrict what a plugin can access.
Drafted with help from AI tools, edited and fact-checked by Steven Liechti.
Related tags
- Obsidian
- Claude Code
- MCP
- Guides
Subscribe to receive notifications of new posts
We'll never share your email address.
Steven Liechti