An Obsidian vault is just a folder of markdown files. That is exactly what makes it a good target for Claude Code. Point the CLI at the folder, and Claude can read, write, move, and reorganize notes the same way it edits a codebase. The catch is that most vaults are organized for a human clicking around, not for an agent that reads files top to bottom. Four rules fix that. None of them are about Obsidian plugins. They are about giving Claude a directory it can navigate cheaply.
The problem nobody talks about
A vault with a few hundred notes and no structure is a search problem for an agent. Ask Claude "update my note on X" and if it does not know where X lives, it falls back on grep and glob across the whole tree. Every one of those reads costs tokens and time, and on a large vault it burns a real chunk of your context window before Claude has done any actual work.
The failure is quiet. Claude still finds the note eventually, so nothing looks broken. You just notice sessions getting slower, answers getting vaguer as the useful context gets crowded out by file listings, and your usage limit arriving sooner than it should. The fix is not a faster model. It is a vault laid out so Claude reads three files instead of three hundred.
Why this changes everything
One map file replaces a full-tree search. If the vault root holds a single markdown file that says where everything lives, Claude reads that one file and jumps straight to the right folder. That turns an open-ended search into a direct lookup. On a vault of a few hundred notes, that is the difference between one read and dozens.
A hard archive shrinks what Claude has to consider. Move dead drafts and finished projects into an archive folder Claude is told to skip, and the live vault it reasons over gets smaller. A smaller search space means faster, tighter answers, because Claude is not weighing notes you stopped caring about six months ago.
Letting Claude file things means the layout stays agent-friendly. When Claude does the organizing, it structures the vault the way it will want to read it next time. That compounds. Every note you add slots into a system a future session already understands, instead of a system you have to re-explain each time.
1. Start every session from the vault root
Open Claude Code with the vault folder as the working directory, then say what you are doing this session before anything else.
cd ~/your-vault
claudeThen a first message like "I'm cleaning up my meeting notes from this week" or "help me draft a note on X." The working directory matters because it scopes every relative path and every file search to the vault. The opening sentence matters because it tells Claude which corner of the vault to load, so it pulls the two or three relevant files instead of scanning for what you might mean.
This is the cheapest habit on the list and the one people skip. Ten seconds of intent up front saves Claude a round of guessing.
2. Keep one root map file
Put a single markdown file at the vault root whose only job is to describe the layout. In Claude Code this is the CLAUDE.md file, which the CLI reads automatically at the start of every session. Even if you use a different agent, the pattern holds: one file, at the root, that maps the territory.
Keep it short. A table is enough:
# Vault Map
| Folder | What lives here |
|-------------|------------------------------------------|
| Projects/ | Active work, one folder per project |
| Notes/ | Reference notes and permanent knowledge |
| Daily/ | Daily logs, newest at the top |
| Archive/ | Finished and dead work. Do not touch. |
## Rules
- Wikilinks use the full path from the vault root.
- New notes go in Notes/ unless they belong to a project.
- Never edit anything in Archive/ unless I say so.The map does two jobs. It tells Claude where to look, and it encodes your conventions so Claude writes new notes the way the rest of the vault is written. Update it when the structure changes. A stale map is worse than none, because Claude trusts it and sends itself to the wrong folder.
3. Archive hard
Make one Archive/ folder and tell Claude, in the map file, never to read or write there unless you ask. Then be aggressive about what goes in. Old research you have mined, drafts that died, projects you finished or abandoned. If you are not actively working on it, it goes in the archive.
## Rules
- Archive/ is off-limits. Do not search it, read it, or edit it unless I explicitly point you there.The archive is not a graveyard you feel bad about. It is a performance setting. Everything you move out of the live tree is one fewer note Claude has to consider on every future search. You keep the history, and you keep it out of the way. When you genuinely need something old, you tell Claude to go look in Archive/, and only then does it read it.
4. Never organize by hand
This is the rule that ties the other three together. Do not sit there dragging notes between folders. Describe the mess and hand it to Claude.
You: These daily notes are a dump. Sort anything worth keeping into
Notes/, move finished stuff to Archive/, and update the map file to
match. Show me the plan before you move anything.Claude will restructure the vault in one pass, far faster than you would by hand, and it will lay things out in the shape it finds easiest to read back later. That last part is the whole point. When the agent picks the structure, the structure serves the agent, so the next session starts from a layout it already understands. Your notes stop being a pile you maintain and start being a system that maintains its own shape.
Ask for the plan before the moves so you can veto anything before files shift. After that, get out of the way.
Honest limitations
This is not free of risk, and it is not zero effort.
Claude moving files is a real filesystem operation. Put the vault under version control first. git init in the vault root, commit before any big reorganization, and you can undo a bad sort with one command. Without that, a wrong move is a manual cleanup.
Obsidian wikilinks break when notes move. If Claude relocates a note, links pointing at it can go stale unless it updates them too. Tell it to fix links as part of any move, and spot-check the result. Obsidian's own link-update feature only fires when you move files inside the app, not when an external tool does it.
The map file is upkeep you now own. It only helps while it is accurate, so every structural change means a one-line edit to the map. Skip that and Claude confidently reads from an outdated picture.
And the archive rule is only as good as your discipline. If half your live vault is dead notes you never moved, Claude is still searching them. The system rewards you for actually pruning.
Quick reference
- Open Claude from the vault root (
cdin first), then state the session's goal in your first message. - Keep one root map file (
CLAUDE.mdfor Claude Code) listing every folder and your conventions. Update it whenever the structure changes. - Keep one
Archive/folder Claude is told to ignore. Move anything you are not actively working on into it. - Hand reorganization to Claude, ask for the plan first, and let it pick the layout.
git initthe vault before you start, so any bad move is onegitcommand to undo.- Tell Claude to fix wikilinks whenever it moves a note.