How to Use Claude Code With Obsidian Without Losing Notes

The safe way to use Claude Code with Obsidian is to make the vault recoverable first, keep source notes read-only, start Claude Code in Plan mode, and allow edits only in a dedicated output folder until you have reviewed a complete dry run. A CLAUDE.md file can explain the workflow, but only Claude Code permissions and a real backup enforce the boundary.

This guide uses four folders: an inbox for new material, an immutable source archive, human-owned notes, and an agent output area. Claude Code can search the whole vault, but it earns broader write access only after its proposed changes are easy to inspect and reverse.

Prerequisites

You need:

• an existing Obsidian vault made of local Markdown files;

• Claude Code installed and authenticated;

• enough free space for a second copy or another working backup;

• a terminal opened at the vault root;

• no secrets, API keys, or private exports inside folders Claude Code may read.

Obsidian warns that sync is not a backup. Before an agent touches the vault, keep an independent copy, filesystem snapshot, or version-controlled checkpoint that you know how to restore.

Step 1: Make the Vault Recoverable

Close Obsidian, copy the entire vault to a separate location, and confirm the copy contains both your notes and the hidden .obsidian configuration folder. If you are comfortable with Git, add a local checkpoint too:

cd "/path/to/your/vault"
git init
git add .
git commit -m "checkpoint before Claude Code"
git status --short

Expected result: the final command prints nothing. If it lists untracked or modified files, review them before continuing. A local Git commit helps with text changes, but it is not a substitute for an independent backup, especially for attachments and files Git does not track.

If the vault already uses Git, do not reinitialize it. Run git status --short, commit or stash reviewed work, and confirm you can restore one test note from history.

Step 2: Separate Sources From Agent Output

Create a small folder contract instead of pointing Claude Code at an undifferentiated vault:

mkdir -p "00 Inbox" "10 Sources" "20 Notes" "90 Agent Output"

Use the folders this way:

Move files only if the new structure fits your vault. You can instead apply the same ownership model to existing folders. The important part is that original material has a stable, protected location and generated work has an obvious review queue.

Step 3: Add Enforced Permission Rules

Open Claude Code in the vault, run /permissions, and add deny rules for the source archive plus destructive shell commands. A project-local .claude/settings.local.json can express the same boundary:

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

Keep the default permission mode for normal work. Use Plan mode for the first inspection. Do not use bypassPermissions on a live vault. Anthropic's permission rules are evaluated deny, then ask, then allow, so a deny rule cannot be canceled by a narrower allow rule.

Expected result: Claude Code can read a note in 10 Sources, but an attempted edit is blocked. Test the rule on a disposable file before relying on it. If the test edit succeeds, stop and inspect /permissions to see which settings file is active.

The exact rule syntax can change as Claude Code evolves. Recheck Anthropic's current permission reference after a major upgrade.

Step 4: Define the Workflow in CLAUDE.md

Create CLAUDE.md at the vault root:

# Vault rules

- Treat `10 Sources/` as immutable evidence. Never edit, move, rename, or delete it.
- Put every first draft in `90 Agent Output/`.
- Do not edit `20 Notes/` until you show the proposed file list and receive approval.
- Preserve YAML properties, wikilinks, embeds, block references, and callouts.
- Cite source notes with links. Do not invent a source or publication date.
- Before finishing, show `git status --short` and a summary of changed files

This file tells the agent how to work, but it is not a security control. Keep the permission deny rules and backup even when the instructions are clear.

Step 5: Run a Read-Only Inventory First

Switch Claude Code to Plan mode and give it a bounded prompt:

Read this Obsidian vault without modifying it.
Report the number of Markdown files in each top-level folder, five recurring tags,
and any broken wikilinks you can identify. Propose one organization improvement.
Do not create, edit, move, rename, or delete files

Expected result: Claude Code returns an inventory and a proposal, while git status --short remains empty. Spot-check its counts and links. If it mistakes a valid Obsidian embed or block reference for a broken link, add that syntax to CLAUDE.md before allowing writes.

This dry run also reveals a common scaling problem: a large vault can overwhelm the useful context window. Ask for an index-first workflow instead of letting the agent load thousands of notes indiscriminately.

Step 6: Allow One Reversible Write

Return to the default permission mode and request one new file in the output folder:

Create `90 Agent Output/vault-map.md` from the inventory you just completed.
Include links to the top-level folders, the five recurring tags, and the proposed
improvement. Do not edit any existing note. Show the final diff

Verify independently:

git status --short
git diff -- "90 Agent Output/vault-map.md"
git diff --name-status

Expected result: exactly one new file appears, and no path has a D, R, or unexpected M status. Open the file in Obsidian and confirm its wikilinks render. Only then should you approve a second, similarly bounded task.

For changes to existing notes, ask Claude Code to produce a patch plan first. Review the exact paths, make one batch, inspect the diff, and checkpoint it before starting another batch.

Step 7: Teach Claude Code Obsidian Syntax

Plain Markdown is not the whole Obsidian format. Properties, wikilinks, embeds, callouts, Bases, and JSON Canvas need specific handling. The kepano/obsidian-skills repository provides Agent Skills for those formats and states that they work with Claude Code and Codex.

Review the repository before installation, especially every SKILL.md, referenced script, and command. Then follow its current Claude Code installation instructions. At the time of writing, its plugin marketplace flow is:

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

Restart Claude Code and repeat the one-file test. A skill improves format knowledge; it does not widen the source folders Claude Code should be allowed to change.

Add Current Research Without Pasting API Keys

Once the local boundary works, you can use Aident Loadout to bring dated external evidence into the inbox through a connected read-only Action:

Follow https://aident.ai/SETUP.md
Find a read-only Action that can search a connected research source.
Inspect its current schema, show the exact query and date window, and run it once.
Save only a Markdown summary with source URLs and publication dates in
`90 Agent Output/research-inbox.md`. Do not modify existing notes

Expected result: the Action uses the connected integration without placing a provider credential in the prompt or vault, and the only local change is the reviewed research file. Keep source URLs and dates so future summaries can be checked against the original evidence.

Common Failure Modes

Claude Code Reorganized the Whole Vault

The request was too broad or the write boundary was not enforced. Restore the checkpoint, return to Plan mode, and restrict the next task to one output file or a reviewed path list.

Obsidian Shows Broken Links After a Rename

File moves can affect wikilinks, embeds, headings, and block references. Do not let the agent batch-rename notes until a disposable test confirms how your current Obsidian settings update links.

Git Shows Constant .obsidian Changes

Workspace layout and plugin state can be noisy. Review the files before excluding anything. Ignore only machine-local state you can safely regenerate, and keep plugin configuration that the vault needs.

The Agent Invented Metadata or Sources

Require links to exact source notes and preserve unknown values as unknown. Generated summaries belong in the review folder until a human verifies names, dates, claims, and citations.

The Vault Is Too Large for a Useful Answer

Create a small index with paths, titles, tags, and dates. Ask Claude Code to read the index first, select relevant notes, and cite every file it opens. More context is not automatically better context.

Why This Setup Works

The backup makes mistakes recoverable. Folder ownership reduces the number of files exposed to a write. Permission rules enforce the source boundary even if a prompt is misunderstood. Plan mode reveals how Claude Code interprets the vault before it can edit. A one-file probe makes success observable in both Git and Obsidian.

The same pattern explains why a specific networking fix can attract durable search traffic: readers need an exact answer, reproducible steps, expected results, and failure modes. A safe Obsidian workflow should be equally concrete.

For the broader capability model, read Agent Skills vs MCP vs CLI. For external tools with less context overhead, use How to Reduce MCP Token Usage in Claude Code and Codex.

Use Aident Loadout to run one scoped read-only research Action, then confirm that exactly one reviewed Markdown file reached your agent output folder.

Sources

• Back up your Obsidian files, Obsidian Help, accessed July 24, 2026

• How Obsidian stores data, Obsidian Help, accessed July 24, 2026

• Configure permissions, Claude Code Docs, accessed July 24, 2026

• Claude Code settings, Claude Code Docs, accessed July 24, 2026

• Agent Skills for Obsidian, GitHub, accessed July 24, 2026

• Agent Skills specification, accessed July 24, 2026

Refresh this guide when Claude Code changes permission modes or rule syntax, Obsidian changes its storage or backup guidance, or the Obsidian skills installation flow changes.