Claude has been open on my screen pretty much all day for a while now. I've got it hooked up to Figma, Canva, and Affinity, I use it for research and design, and a few weeks ago I connected it to my Obsidian vault through the filesystem connector - which turned out to be way simpler than I'd assumed. No MCP setup needed, just point it at the vault folder path. Claude could now browse my notes, sort files into folders, and clean things up on request, all from within the chat space.

Then I asked it to rename some files and came back to a vault with half my dashboard links broken.

The filesystem connector doesn't know it's in Obsidian. It sees a folder of .md files and that's the extent of it - wikilinks, callout syntax, frontmatter, none of it registers as anything with rules attached. So when Claude renames a file, Obsidian never finds out, and everything pointing at that filename stays pointing at something that no longer exists. There's a fix for this though, and it's a single plain text file sitting in your vault root.​​​​​​​​​

The filesystem connector isn't aware it's in Obsidian

And it can break your Obsidian setup

The connector operates at OS level. It sees .md files in a folder and that's pretty much the whole picture. There's no vault logic or awareness that filenames are load-bearing, and it has no concept of the internal system you've built on top of those files.

That last part is what got me. Every [[wikilink]] in your vault points at a filename. The second that file gets renamed or moved through anything other than Obsidian itself, the link dies because Obsidian's auto-update feature only fires when the rename happens from inside the app. Claude is working at OS level, so Obsidian never gets the memo.

And it's not just wikilinks. Callout syntax can break, frontmatter can get corrupted, and ![[embeds]] follow different rules than standard Markdown images. Claude can "fix" all of these because it doesn't know they're Obsidian-specific. As far as it's concerned, it's just looking at a slightly unusual Markdown. The instinct after my first broken dashboard was to stop letting Claude touch files altogether, which defeats most of the reason I set this up.​​​​​​​​​​​​​​​​

The fix is a single file in your vault root

And you can set it up in five minutes

The solution is in setting up a CLAUDE.md file and dropping it in the root of your vault. You can write in Notepad or VS Code or Obsidian itself, or even just ask Claude to make it for you. It can generate a starter version based on your vault's structure, and then you can tweak it yourself. Either way, once it's in there, Claude reads it when it accesses your vault and treats it as standing instructions for that session.

Worth flagging: in Desktop chat it's not fully automatic the way it is in Claude Code. Just make a habit of starting vault sessions with "check my CLAUDE.md first" and Claude will read it before doing anything.

The file itself is where the real work happens. A solid CLAUDE.md for an Obsidian vault needs a few specific things. Your folder structure and naming conventions, so Claude knows where things live and where new files should go. The Obsidian-specific syntax rules - that [[double brackets]] are wikilinks and not standard Markdown links, that callout syntax requires exact formatting, that frontmatter is a YAML block Obsidian parses for metadata, that embed syntax for images and PDFs follows different rules than regular Markdown images. Claude needs to be told these things explicitly because nothing about the files signals it on their own.

Then the safety rules, which are probably the most important part. Scan for inbound [[wikilinks]] before renaming or moving anything. Never rename a file that appears in graph view without explicit permission. Safe zones are inbox files, raw dumps, and new drafts with no inbound links - anything else, ask first. You can also flag specific folders as completely off-limits, such as templates, certain archive folders, or anything historical you don't want touched. I didn't have any no-go folders in my vault, it doesn't contain my personal journal or information I won't be able to retrieve back anywhere else, so I didn't include this part.

You can update the file whenever your vault structure changes. Open it directly in a text editor, or just ask Claude to edit it through the filesystem connector.

What this actually changed for me

The before and after

The obvious upside is that I can let Claude reorganize again without babysitting it because the safety rules are baked into the file. When it moves files it places them correctly now, and when it creates notes they come out with the right frontmatter and wikilink format. The CLAUDE.md also ended up being a useful record of how my vault is structured (for me as much as for Claude, at least).

But the real downside being honest about: reorganizing files now has an extra friction point. Claude will pause and check for inbound links before touching anything, which is the right behavior, but now the workflow is slower than it used to be.

A file I should have added from the start

The filesystem connector is still the right call for most Obsidian users who don't want to set up MCP. It just needs a little context to work safely. CLAUDE.md is that context. You only have to write it once, and maybe update it here and there, and Claude stops messing with your vault.