Obsidian + Claude Code: set up your vault as a second brain

Updated 9 min read

To use Claude Code with Obsidian, start Claude Code in your vault folder. A vault is a folder of markdown files, so Claude Code can read, search, write and link your notes without a plugin, and Obsidian picks up its changes as they happen. Add a CLAUDE.md that says where notes go and how to link them, keep Claude out of the .obsidian folder, and keep the vault in Git so you can review every change.

How do I run Claude Code in my Obsidian vault?

Obsidian’s docs say it stores notes as markdown plain text files in a vault, and a vault is a folder on your local file system. Other editors can change those files, and Obsidian refreshes to keep up. Claude Code works on the files in the directory you start it from, so:

cd ~/path/to/your/vault
claude

If you start Claude Code from a project instead, --add-dir adds the vault as a second directory it can use (claude --help lists it as “Additional directories to allow tool access to”):

claude --add-dir ~/path/to/your/vault

Then work the way Andrej Karpathy describes in his LLM wiki gist: the agent open on one side, Obsidian on the other. The agent edits pages as you talk, and you browse the results in real time, “following links, checking the graph view, reading the updated pages.” His summary: “Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.” An Obsidian second brain run by Claude Code is that setup with your own notes in it.

How should I lay out the vault for Claude Code?

Claude does better with a few fixed places than with a free-form vault. A layout that follows Karpathy’s gist and suits personal notes:

vault/
  CLAUDE.md          # the rules Claude reads every session
  .claude/           # Claude Code settings and skills for this vault
  .obsidian/         # Obsidian's settings; Claude stays out
  inbox/             # quick captures and voice note transcripts
  raw/               # sources you keep as they are: articles, papers, transcripts
    assets/          # images and attachments
  notes/             # pages Claude writes and keeps current, one topic each
  daily/             # daily notes
  templates/
  index.md           # every page in notes/, one line each
  log.md             # append-only record of what Claude did

Three rules keep it working:

  • One vault, not vaults inside vaults. Obsidian’s docs warn that internal links are local to a vault, so links in nested vaults may not update correctly.
  • Sources are read-only. raw/ is what you collected. Claude reads it and writes about it in notes/, so a summary never replaces the original.
  • An index and a log. index.md is where Claude starts when it answers a question. Karpathy says an index like this works at about 100 sources and hundreds of pages without embedding search. log.md tells you, and the next session, what was done.

The gist also suggests setting Settings → Files and links → Attachment folder path to a fixed folder such as raw/assets/, so images land where Claude expects them.

What goes in a CLAUDE.md for an Obsidian vault?

Claude Code reads the CLAUDE.md in the directory you start it from at the beginning of every session. In a code repository, /init writes one from what it finds in the codebase. A vault has no build files to read, so write this one yourself and keep it under 200 lines, as Anthropic’s memory docs advise. Our CLAUDE.md guide covers the format. A starting point for a vault:

# Vault rules

This is my Obsidian vault. You maintain notes/; I read it in Obsidian.

## Where things go
- Captures land in inbox/. File what they say into notes/,
  then move the capture to inbox/done/.
- raw/ holds sources. Read them. Never edit, move or delete them.
- One topic per page in notes/. File names: lowercase-with-dashes.md
- Never touch .obsidian/.

## Links
- Link pages with [[wikilinks]] by file name, without .md.
- Before you create a page, search for one on the topic and update it instead.
- Every new page links to at least one existing page and gets a line in index.md.
- Rename or move notes with `obsidian rename` or `obsidian move`, not `mv`.

## Pages
- Frontmatter: tags, source (the raw/ file or URL), updated (YYYY-MM-DD).
- When a source contradicts a page, keep both claims with their dates and say so.

## Log
- After each task, append to log.md: `## [YYYY-MM-DD] ingest | Title`

If you also run Codex or another coding agent in the vault, put the shared rules in AGENTS.md and make @AGENTS.md the first line of CLAUDE.md. By default Claude Code reads AGENTS.md only when there is no CLAUDE.md in the folder or above it, so the import keeps both. Rules that are only for you can go in CLAUDE.local.md.

What should I let Claude Code write?

Let it Ask first Keep it out
Write and update pages in notes/ Delete notes .obsidian/ (settings, themes, plugins)
Append to log.md and daily notes Rename or move notes raw/, once a source is in it
Keep index.md current Edits across dozens of pages Journals and notes you want in your own words
Add frontmatter and tags Change the folder layout

A permission deny rule backs up the last column whatever the conversation says. Put it in the vault’s .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Edit(/.obsidian/**)",
      "Edit(/raw/**)"
    ]
  }
}

In project settings, a path that starts with / is relative to the project folder, here the vault. Use Edit for raw/, not Read: Anthropic’s permissions docs say a Read deny also blocks edits, but it would stop Claude reading your sources too. The same docs note that deny rules cover Claude’s own file tools and the file commands it recognizes in Bash, not a script that opens files itself. For that, they point to the sandbox.

For questions about your notes, plan mode lets Claude read and explore without editing.

Then keep the vault in Git. git diff after a session shows every line Claude changed, and you can revert what you don’t want. Obsidian’s docs suggest adding .obsidian/workspace.json and .obsidian/workspaces.json to .gitignore, because they change every time you open a file.

Links are what turn a folder of notes into a second brain, and they need the most guidance. Check two settings under Settings → Files and links: Use Wikilinks, so Obsidian and Claude write links the same way, and Automatically update internal links, which updates links when you rename a file.

In graph view, circles are notes and lines are links, and a note gets bigger the more notes link to it. After Claude files a batch of sources, open the graph and look at its shape. Karpathy uses it to see “which pages are hubs, which are orphans.” A new page with no lines was never linked in. Turn off Existing files only in the graph’s filters to show notes that are linked to but not written yet; those are often the next pages worth asking for. Add raw/ or templates/ to Excluded files in settings to keep them out of the graph.

To see a vault’s graph without opening Obsidian, open the folder in our free wiki graph viewer. It reads the files in your browser and uploads nothing, and it opens public GitHub repositories of markdown too.

Should Claude Code use Obsidian’s CLI or an MCP server?

Claude Code needs neither to read and write notes. Each helps with things a plain file edit cannot do.

Obsidian CLI controls the desktop app from your terminal. It needs the Obsidian 1.12.7 installer or later: turn on Settings → General → Command line interface and follow the prompt to register it. The app has to be running; if it is not, the first command launches it. When the terminal is in a vault folder, the CLI uses that vault, so Claude Code started in the vault can call it directly. Commands from Obsidian’s docs that suit an agent:

obsidian search:context query="pricing"    # matches as path:line: text
obsidian backlinks file="Project Atlas"     # notes that link here
obsidian orphans                            # notes with no incoming links
obsidian unresolved                         # links to notes that don't exist yet
obsidian move file="Old note" to=notes/archive/
obsidian property:set name=status value=done file="Project Atlas"
obsidian daily:append content="- [ ] Review what Claude filed"

move and rename are the ones to name in your CLAUDE.md. Obsidian’s docs say they update internal links when Automatically update internal links is on. A rename Claude does with mv goes around Obsidian, and the docs make no such promise for it.

MCP servers. Obsidian’s help docs describe no MCP server of their own; the ones people use are community projects. They matter most for agents that cannot run commands in your vault folder, such as Claude Desktop. Our Obsidian MCP guide compares three, with their tools and config. For Claude Code inside the vault, the folder plus the CLI covers most needs without another server to keep running.

How do I save routines like processing the inbox?

Turn a routine you repeat into a skill. Claude Code’s skills docs say a SKILL.md in .claude/skills/<name>/ creates a /<name> command, and that older .claude/commands/ files keep working. A vault skill at .claude/skills/inbox/SKILL.md:

---
description: Files inbox/ captures into notes/. Use when I say "process the inbox".
---

For each file in inbox/ (not inbox/done/):
1. Read it and find the notes/ pages it belongs to. Search before creating a page.
2. Update those pages, or write a new one. Link with [[wikilinks]].
3. Add any new page to index.md.
4. Move the capture to inbox/done/ and append one line to log.md.
Then list what you changed and anything you were unsure about.

Type /inbox to run it. Karpathy prefers to take one source at a time, read the summary and steer what the agent emphasizes. When you correct the same thing twice, add the rule to CLAUDE.md or the skill.

How do I give my other agents the same notes?

A vault lives on one machine. Claude Code there can use it, and so can Codex in the same folder through AGENTS.md. Past that it gets harder:

  • Agents elsewhere can’t reach it. Claude on the web, ChatGPT or an agent on a server cannot read a folder on your laptop, or an MCP server running there.
  • Copies drift. Obsidian lists Obsidian Sync, Dropbox, iCloud, OneDrive and Git as ways to sync a vault. Each copies files, so every agent writes to its own copy, and two agents editing one note at once can clash.
  • Nobody signs their edits. A folder doesn’t record which agent changed a line. Git records commits under whatever author name each agent was given.

Share it with your other agents

Dexio is a hosted wiki that AI agents read and write through MCP. Claude Code, Codex, Cursor, Hermes Agent, OpenClaw, Claude and ChatGPT list, read, search, write, edit, move and link markdown pages in one shared wiki, and you see what your agents know as a page graph at app.dexio.wiki. Pages use [[wikilinks]]. Every change is kept with the name of the agent that made it, and passing base_version stops one agent from overwriting another’s edit. It is open source (AGPL-3.0) and hosted, free for one person, with Team at $10 and Business at $20 a member a month. Any wiki downloads as markdown.

Dexio does not sync with your vault, so you choose what goes where. One way to split it: personal notes and journals stay in Obsidian, and the knowledge your agents share (decisions, research, how your projects fit together) goes in the wiki. To connect Claude Code, send it:

Connect yourself to my Dexio wiki. The steps are at https://dexio.wiki/agents.md: read the whole file, not a summary, and follow them.

Then add a line to the vault CLAUDE.md that says which knowledge belongs in the wiki. The Claude Code memory guide covers setup and troubleshooting. For Karpathy’s pattern in a vault, see LLM wiki in Obsidian, and for the wider picture, our post on Obsidian AI.

FAQ

Does Claude Code need an Obsidian plugin? No. It edits the markdown files in the vault folder, and Obsidian refreshes to show the changes. The CLI and MCP servers are optional.

Does Claude Code read my whole vault every session? No. It loads CLAUDE.md (and its auto memory) when a session starts and reads other notes when a task needs them. An index.md helps it find the right ones.

Can Claude Code break my vault? It can make edits you didn’t want. The default permission mode asks the first time Claude uses each tool; acceptEdits stops asking about file edits. Keep the deny rules and Git, and review git diff.

Sources

Ask a question

Ask anything about Dexio.

About
We reply by email.