How to use Claude Code with your Obsidian vault

Claude Code works on an Obsidian vault with no plugin and no setup, because a vault is a folder of markdown files. Open a terminal in the vault, run claude, and it reads and edits your notes with the same file tools it uses on code. A CLAUDE.md file in the vault root tells it how your notes are organized, and Obsidian shows that file as an ordinary note.

The four setups below differ in what sits between the agent and your notes. Two failures matter most when you choose: a note overwritten from a stale copy, and wikilinks broken when the agent renames a file.

Four ways to connect Claude Code to a vault

Option	Obsidian must be running	What it adds	What it costs you
1. Claude Code in the vault folder	No	Nothing to install	No guard against stale overwrites or broken links
2. Jotura’s CLI	No	Hash-checked edits, link-aware renames, diff previews	A separate app to install, closed source, no Obsidian plugins
3. Obsidian CLI (official, 1.12.7+)	Yes, and the first command launches it	Obsidian’s own commands, link-aware rename and move	Needs a desktop session, so it cannot run on a headless server
4. Local REST API with MCP plugin	Yes	An MCP server with edits aimed at a heading, block or frontmatter field	A third-party plugin holding a key to your whole vault

Option 1 is the base for the other three, so its setup applies whichever you pick. For agents that edit existing notes, Option 2 is the one we recommend, for the reasons given under it below.

Option 1: Claude Code in the vault folder

The whole setup is two commands:

cd ~/Notes
claude

Claude Code loads CLAUDE.md from the folder you start it in and every folder above it. A subfolder’s own CLAUDE.md, such as Daily/CLAUDE.md, loads the first time Claude touches a file there.

Working from a code project with --add-dir

To keep a code project as the working directory and read your notes alongside it, add the vault:

claude --add-dir ~/Notes

An added directory grants file access and little else. Claude Code skips its CLAUDE.md unless you launch with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 set, and it ignores the permission rules in the vault’s .claude/settings.json. Put vault rules in the project’s settings or in ~/.claude/settings.json instead, with a home-relative path such as Edit(~/Notes/.obsidian/**).

Write a vault CLAUDE.md

Keep the file to what Claude would otherwise guess wrong. Anthropic recommends under 200 lines per file, and this example for a vault with projects, daily notes and an inbox runs to about 20:

# About this vault
Personal notes, edited in Obsidian on a laptop and a phone.

## Layout
- `Projects/<name>/` holds one folder per active project. `Projects/_Archive/` is finished work.
- `Daily/YYYY-MM-DD.md` is the daily note. Add lines under `## Log`. Never rewrite earlier lines.
- `Inbox/` is where you put anything new unless I name a folder.
- `Attachments/` holds images and PDFs. Leave it alone.

## Conventions
- Link notes with [[wikilinks]], never markdown links.
- Every note has `created` and `tags` in its frontmatter. Keep both when you edit.
- Tasks use `- [ ]`. Mark done with `- [x]`, never delete a task.

## Ask me first
- Before renaming, moving or deleting any note. List the change and wait for my yes.
- Before editing more than five existing notes in one task.

## Never
- Never edit anything in `.obsidian/`.

Claude treats every line here as an instruction it can still break. What to put in CLAUDE.md covers what earns a line and what to leave out.

Turn the rules that matter into permissions

Claude Code enforces permission rules itself, whatever the model decides. Create .claude/settings.json in the vault root:

{
  "permissions": {
    "deny": [
      "Edit(/.obsidian/**)",
      "Bash(mv *)",
      "Bash(git mv *)",
      "Bash(rm *)"
    ]
  }
}

A leading / anchors the path at the folder you started Claude in, so Edit(/.obsidian/**) means the vault’s own settings folder. Edit rules cover every built-in tool that writes files, file commands Claude Code recognizes in the shell such as sed and tee, and the targets of > redirects. The mv rule matters because acceptEdits mode approves mv, cp and mkdir inside the working directory without asking.

On Windows, where Claude may use PowerShell, add PowerShell(Move-Item *), PowerShell(Rename-Item *) and PowerShell(Remove-Item *). Claude Code matches aliases such as mv and ren to those cmdlets.

These rules stop the direct route only. A Python or Node script that opens files itself gets past them, and so does any other program Claude runs, including obsidian and jotura, since those tools write files themselves. The git baseline below catches what the rules miss. The full syntax is in Anthropic’s permissions documentation.

Put the vault in git

Git gives you a diff of every agent change and a one-line undo. Start with a .gitignore for files that change on their own:

# Obsidian rewrites these every time you open a note
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/
# Claude Code personal files
.claude/settings.local.json
CLAUDE.local.md
# Jotura's lock and search cache, when you use its CLI
.jotura/

cd ~/Notes
git init
git add -A
git commit -m "Vault before Claude Code"

A sync service such as iCloud, Dropbox or Obsidian Sync is no backup here, because a bad edit syncs to every device within seconds. The .git folder syncs along with the vault, and two machines committing at once can leave the repository broken, so commit from one machine.

Your first session

Start with a task that reads widely and writes one new file, which is trivial to undo.

1. Start in plan mode

claude --permission-mode plan

In plan mode Claude reads files and runs read-only shell commands without asking, and leaves your notes unedited. Any other shell command still goes through the usual approval prompt, so read what it asks before you accept. Give it a question that crosses folders:

Read CLAUDE.md, then look through Projects/. List every open task (- [ ]) in a
note that hasn't been modified in the last 30 days, grouped by project.
Don't change anything.

A wrong folder or a missed task in the answer tells you what to add to CLAUDE.md.

2. Allow one additive write

Approve the plan or start a normal session with claude, then ask for a single new note:

Write that list to Inbox/Stale tasks.md as a checklist. Link each task's
source note with a wikilink. Don't edit any other file.

3. Review what changed

git status --short

Expect one line: ?? "Inbox/Stale tasks.md", or ?? Inbox/ when the folder held no tracked files before. A line starting with M or D is a file the agent changed or deleted. Run git diff to read the changes, then open the new note in Obsidian and confirm every wikilink resolves.

/rewind in Claude Code, or Esc twice on an empty prompt, restores edits made by Claude’s own file tools. It does not track shell commands such as mv and rm, which git restore <path> undoes for a tracked file. Commit once the result is right:

git add -A
git commit -m "Claude: stale task list"

Repeat that loop of plan, small write, git status and commit until you trust the agent’s judgment on your vault.

What goes wrong, and why

A whole-file write from a stale read

Claude Code’s Edit tool replaces an exact string matched against the file’s current contents, so a paragraph you added elsewhere in the note survives. Its Write tool replaces the whole file with whatever Claude composed. A shell command such as sed -i, or a script, does the same.

The loss happens when the agent reads a note, works for a few minutes, then writes the whole file from that old copy. Anything you typed and Obsidian saved in between is gone, with no error. Obsidian autosaves within about two seconds.

Obsidian has merged outside changes with unsaved edits automatically since version 0.11.6, and it shows a notice when it does. Forum reports describe merges that dropped or duplicated lines. Close a note in Obsidian, or stop typing in it, while the agent works on it, and check the note after any merge notice.

A rename with mv breaks every wikilink

Obsidian rewrites links when you rename a note, provided Automatically update internal links is on under Settings, Files and links. It only does this for renames Obsidian performs. An agent’s mv "Old name.md" "New name.md" looks to Obsidian like one file vanishing and another appearing, and every [[Old name]] in the vault points at nothing.

Search-and-replace repairs are fragile. A wikilink can carry an alias ([[Old name|label]]), a heading ([[Old name#Goals]]), a block reference or a folder path, and a replacement that misses one form leaves dangling links. Use a tool that rewrites links as part of the rename, as the Jotura CLI and the Obsidian CLI both do, or rename in Obsidian yourself.

Wikilinks and backlinks in plain markdown covers every link form a rename has to handle.

Option 2: Jotura’s CLI, with Obsidian open or closed

This is the route we recommend once the agent edits existing notes, because it guards against both failures above. Jotura is a markdown notes app whose desktop installer includes a command line tool, jotura, that opens an Obsidian vault as it is. Obsidian does not need to be running. Install the app from the download page; on Windows and Linux the CLI lands on your PATH, and on macOS you add it from Settings, Advanced, Command-line tool.

Read-only commands write nothing into the vault. Commands that walk the vault, such as ls, search, grep and backlinks, skip .obsidian/ and .trash/, and the CLI never writes into .obsidian/ on its own. An explicit path is still obeyed: jotura edit .obsidian/app.json edits that file, and your Edit(/.obsidian/**) deny rule does not stop it. The CLI reads app.json, daily-notes.json and templates.json from .obsidian/ to match your attachment folder, daily notes and templates.

How it finds your vault

Each command resolves a vault in a fixed order: the --vault flag, then the JOTURA_VAULT environment variable, then the vault the Jotura desktop app last opened. A command that finds no vault exits with code 6.

export JOTURA_VAULT=~/Notes
jotura status --json

Edits that refuse to overwrite you

The safe loop is read, change, then write only when the note is unchanged:

jotura read "Projects/Acme/Kickoff brief.md" --json
jotura edit "Projects/Acme/Kickoff brief.md" \
  --replace "Budget: TBD" --with "Budget: agreed on the October 3 call" \
  --if-hash <hash-from-read>

A note that changed between the read and the write makes the edit fail with exit code 2, so a paragraph Obsidian saved in the meantime survives. A --replace that matches more than once exits 4 instead of guessing. Edits touch only the note body, leaving frontmatter byte for byte as it was.

To see an edit before it happens, add --dry-run --diff:

jotura edit "Daily/2026-10-10.md" --append --content "- Sent Acme the revised scope" --dry-run --diff

Renames that keep links working

jotura backlinks lists the notes that link to a note. jotura rename rewrites every wikilink, embed and markdown link that pointed at it, keeping aliases and heading anchors:

jotura backlinks "Projects/Acme/Kickoff brief.md"
jotura rename "Projects/Acme/Kickoff brief.md" "Projects/Acme/Acme kickoff.md" --json

The JSON output reports linksUpdated. Each link rewrite is hash-checked, so a note you edit during the rename is never overwritten. The first hash-checked write creates a .jotura/ folder for its lock file, which is why it appears in the .gitignore above.

Once the CLI works, change the rename line in your vault CLAUDE.md to allow renames through jotura rename only. Keep the Bash(mv *) deny rule as the backstop.

Teaching Claude to use it

Jotura’s skills teach Claude to read before every edit and to keep decisions as notes between sessions. Install them inside Claude Code from the jotura-agents marketplace:

/plugin marketplace add adamrichardson14/jotura-agents
/plugin install jotura@jotura-agents

The installed skills are files you own and can edit, and other agents copy them from the jotura-agents repository. Giving AI agents persistent memory covers how the agent keeps memory in the vault, and every command is in the CLI reference.

You install the Jotura desktop app to get the CLI, even if you keep writing in Obsidian, and the app opens the same vault as it stands. Jotura is closed source, and the app has no plugins and no graph view. The app and CLI are free, and only sync is paid.

Option 3: the official Obsidian CLI

Obsidian added a command line tool in version 1.12. It needs the 1.12.7 installer or later, so an in-app update from an older installer is not enough. It runs on macOS, Windows and Linux, once you turn it on under Settings, General, Command line interface.

obsidian search query="quarterly review" format=json
obsidian search:context query="quarterly review"
obsidian daily:append content="- [ ] Call the landlord"
obsidian backlinks file="Kickoff brief"
obsidian rename path="Projects/Acme/brief.md" name="Kickoff brief"
obsidian move path="Inbox/Ideas.md" to="Projects/Acme/Ideas.md"

rename and move update internal links when Automatically update internal links is on. Target a specific vault with vault=<name> as the first parameter. Obsidian must be open, and the first command launches it when it is closed, so the CLI needs a desktop session.

Steph Ango, Obsidian’s CEO, publishes an obsidian-cli skill that teaches Claude these commands, in his obsidian-skills repository. With it in place, the rename line in your vault CLAUDE.md can allow obsidian rename and obsidian move, with the Bash(mv *) deny rule kept as the backstop.

Option 4: the Local REST API with MCP plugin

Local REST API with MCP is a community plugin that serves your vault over HTTPS on your own machine, behind an API key. Version 5.0.0 added a built-in MCP server (Model Context Protocol, the standard Claude Code uses to talk to external tools), and the current release is 5.4.0 (October 6, 2026). Claude Code connects to it with the API key from the plugin’s settings, and your system has to trust the certificate the plugin generates, or you enable its plain HTTP endpoint instead.

The plugin’s patch operation inserts text under a specific heading, after a block reference or into one frontmatter field, so the agent never rewrites a whole note. Since 5.4.0 it refuses to touch the .obsidian configuration folder unless you turn on Allow access to the configuration directory in its advanced settings. It needs Obsidian running, and it is third-party code that can read and change every note.

Its API key sits in .obsidian/plugins/obsidian-local-rest-api/data.json, readable by Claude when it runs in the vault. CLI tools vs MCP servers for agents compares the two styles of integration.

Running Claude Code inside Obsidian

All four options run Claude Code in a terminal beside your notes. Community plugins can also bring it into the Obsidian window: the Claude Code MCP plugin lets Claude see the active note through /ide, and the Terminal plugin embeds a shell pane. Starter vaults such as Noah Brier’s claudesidian ship folders, a CLAUDE.md and skills. The rules in this guide apply unchanged to all of them, since Claude edits the same files.

What to delegate and what to keep

Decide by how easily a change can be undone.

Change	How you undo it	Who does it
Search, summarize, answer questions	Nothing to undo	The agent
A new note, or lines appended to a daily note	Delete the file or the lines	The agent
An edit inside an existing note	git diff, then git restore	The agent, reviewed
The same edit across many notes	Revert a commit touching dozens of files	The agent, after a dry run you read
Rename or move	Rename back, then repair every inbound link	You, or a link-aware tool
Delete	Git or the trash, once you notice	You

Keep deletion for yourself even with a trash folder, so a vague instruction can never remove a note. A folder reorganization rewrites links across the vault, which makes it your decision to take.

Which option to choose

The plain folder covers reading, searching and drafting new notes. Add a CLAUDE.md, the deny rules and git, and do renames in Obsidian.

For an agent that edits existing notes, use Jotura’s CLI. It opens the vault as it stands, and an edit carrying the hash the agent read is refused when the note changed since, a loop the Jotura skills teach. Renames rewrite every inbound link, with Obsidian open or closed. Its limits: you install a separate, closed-source app to get it, and it runs none of Obsidian’s plugins or commands.

Stay with the Obsidian CLI when you want Obsidian’s own commands and plugins in the loop and keep the app open while the agent works. The REST API plugin is the one option here with edits aimed at a heading or block from an MCP client. A notes app with a CLI compares Jotura’s CLI with more alternatives.

Frequently asked questions

Do I need an MCP server to use Claude Code with Obsidian?

No. Claude Code reads and edits the markdown files directly. The MCP server in the Local REST API with MCP plugin adds edits aimed at a heading, block or frontmatter field, and it needs Obsidian running.

Will Claude Code break my wikilinks?

It will when it renames or moves notes with mv or a script, because Obsidian only updates links for renames it performs itself. Block mv with a Bash(mv *) deny rule, and rename with a tool that rewrites links as part of the rename, such as jotura rename or obsidian rename, or in Obsidian itself.

Is it safe to keep Obsidian open while Claude Code edits notes?

For different notes, yes. For the same note, the risk is an agent writing the whole file from a copy it read minutes earlier, which overwrites what Obsidian saved since. Obsidian merges outside changes with unsaved edits automatically, and those merges have dropped or duplicated lines, so stop typing in a note while the agent writes to it.

Can Claude Code see my Obsidian plugins and settings?

Yes, when you start it in the vault, because .obsidian/ is an ordinary folder inside it. Plugin settings live in .obsidian/plugins/<plugin-id>/data.json, and the REST API plugin’s API key is among them. A Read(/.obsidian/**) deny rule blocks Claude’s Read tool and commands such as cat there, though a recursive grep or a script can still reach the folder.

Can Claude Code work on my vault on a server without Obsidian?

Yes, as plain files. Jotura’s CLI works there with hash-checked edits and link-aware renames, though it never syncs, so the vault has to reach the server another way, such as git. Obsidian Headless, an open beta client, syncs a vault to a server and needs an Obsidian Sync subscription. The Obsidian CLI and the REST API plugin both need the desktop app, so neither works there.