
Your planning and design notes pile up in Obsidian, but your coding agent only sees the code repository. This post walks through an Obsidian and Claude Code setup that lets coding agents like Claude Code or Codex read and write the notes in your vault.
Earlier posts covered how to write a note as a work order and how to split an idea into issues. This one covers the step before that: connection and configuration. How to link the folders, what to put in the rules file, what to lock down so your notes survive, and how to use the skills and CLI that Obsidian ships officially.
How to connect an Obsidian vault to a code repository#
A vault is just a folder of Markdown files. So for an agent, the only question is whether it can reach that folder. Dylan Boudro's Obsidian + Claude Code integration guide lays out several ways to connect them. These three work well for coding.
| Approach | How | Good fit when |
|---|---|---|
| Vault as working directory | Run the agent from the vault root | Most of the work is notes, planning, and specs |
| Symlink | Create a link inside the vault to the code repo | One vault covers several projects |
| One vault per repo | Open the repo itself as a vault | You want docs versioned together with the code |
A symlink takes one command. Run it inside the vault folder.
# Link the code repo into the vault under the name my-app
ln -s ~/projects/my-app my-appThe same guide lists the caveats. Symlinks can cause problems on Obsidian Mobile, and with one vault per repo you should add the .obsidian/ folder to .gitignore.
Claude Code gives you one more option. Run it from the code repository and open the vault as an extra directory with --add-dir. The working directory stays in the code repo, and the agent can read your notes too.
# Run from the code repo and open the vault folder as well
claude --add-dir ~/vaultThis approach grants file access only. According to the Claude Code memory docs, instruction files in a directory added with --add-dir aren't loaded by default. A CLAUDE.md loads once you set the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 environment variable, but an AGENTS.md still doesn't. The vault's permission rules covered below don't apply this way either. To use the rules and permissions, run the agent from the vault root.
Write the rules in an AGENTS.md at the vault root#
Connecting the folders doesn't tell the agent what the vault is. It needs to know what lives in which folder and what it must not touch. That's the job of the instruction file at the vault root. I keep a single AGENTS.md. Codex reads it, and per the same memory docs, Claude Code v2.1.277 and later reads AGENTS.md directly when there's no CLAUDE.md. With one file, you never have to keep the same content in sync per agent. On an older Claude Code, add a CLAUDE.md next to it containing only the line @AGENTS.md.
In his essay on Obsidian vaults and Claude Code, Kenneth Reitz describes filling this file with a vault overview, writing conventions, and a list of things not to do. Adapted for coding work, it looks like this.
# Vault guide
## Structure
- `specs/` specs and design notes per feature
- `decisions/` technical decisions and the reasons behind them
- `tasks/` task notes handed to agents
- `sources/` original external material
## Conventions
- Link notes to each other with `[[wikilinks]]`
- New notes get `type`, `status`, and `date` in the frontmatter
## Don't
- Don't create new files unless asked
- Don't edit, move, or delete anything in `sources/`
- Before editing existing notes, show the list of files you plan to changeThe Don't section matters most. Agents often tidy up things you never asked them to. Tests catch a bad change in code, but notes have no such safety net.
Safety guards to set before an agent touches your notes#
An instruction file is only a request. In How to Use Claude Code With Obsidian Without Losing Notes, Adam Reed points out that only Claude Code permissions and a real backup actually enforce the boundary. These parts of that post carry over directly to coding work.
- Make a Git checkpoint first — Commit before the agent touches the vault. The post also notes that sync is not a backup.
- Give each folder a role — Source material is read-only, existing notes need a proposal before edits, and the agent gets a separate output folder it can write to freely.
- Start with read-only work — Have the agent inspect the vault in plan mode first, then let it write a single file.
- Check the changes every time — Use
git status --shortandgit diffto see what changed.
If you run Claude Code from the vault root, permission rules can stop the agent's edit tools from changing the source folder. Add a deny rule to .claude/settings.json in the vault.
{
"permissions": {
"deny": ["Edit(/sources/**)"]
}
}According to the Claude Code permissions docs, a path that starts with / in project settings is relative to the project root. Rules are evaluated in the order deny, ask, allow, so an allow rule can't reopen a path that a deny rule blocks.
This rule blocks file edits. Shell commands like rm or mv need their own rules such as Bash(rm *), and the same docs note that Bash rules aren't a security boundary. That's why the Git checkpoint in step 1 is your last safety net.
Teach the agent Obsidian syntax with obsidian-skills#
Obsidian-specific syntax like wikilinks, callouts, and properties differs from plain Markdown, so you have to teach it to the agent. The obsidian-skills repository, maintained officially by Obsidian, fills that gap.
Agent Skills are bundles of instructions that an agent loads when it needs them. Per the repository, the skills follow the Agent Skills specification, so any skills-compatible agent can use them, including Claude Code, Codex, and OpenCode.
| Skill | What it teaches |
|---|---|
| obsidian-markdown | Obsidian Markdown: wikilinks, embeds, callouts, properties |
| obsidian-bases | Bases (.base) files with views, filters, and formulas |
| json-canvas | JSON Canvas (.canvas) files made of nodes and edges |
| obsidian-cli | Working with vaults through the Obsidian CLI |
| obsidian-headless | Syncing and publishing vaults without the desktop app |
| defuddle | Extracting clean Markdown from web pages |
| knap | Rendering Markdown templates from JSON or CSV data |
The install commands are in the repository README. In Claude Code, install it as a plugin.
# Add the obsidian-skills marketplace to Claude Code and install it
claude plugin marketplace add obsidianmd/obsidian-skills
claude plugin install obsidian@obsidian-skillsFor Codex, the README says to run codex plugin marketplace add obsidianmd/obsidian-skills and then install Obsidian from the plugin directory. To install manually, copy the repository's plugins/obsidian/skills/ folder to .claude/skills/ at your vault root for Claude Code, or to ~/.agents/skills for Codex.
Search the vault and read notes with the Obsidian CLI#
An agent can open and read files directly, but the Obsidian CLI exposes the search, tag, and backlink data Obsidian has already built, as terminal commands. The Starmorph guide above also ranks the CLI as the fastest and most token-efficient way to connect Claude Code to Obsidian.
Turn on the Obsidian CLI#
According to the official Obsidian CLI docs, you need the Obsidian 1.12 installer, and setup goes like this.
- Upgrade to the latest Obsidian installer version (1.12.7 or later).
- Enable Command line interface under Settings → General.
- Follow the prompt to register the CLI, then reopen your terminal.
One thing to know: the CLI works by connecting to the running Obsidian app. If the app isn't running, the first command launches it. For syncing without the desktop app, the docs point to Obsidian Headless instead.
Read commands agents use most#
Parameters take the form name=value. I ran the commands below against my blog vault.
# List every available command
obsidian help
# Search the vault for a keyword (returns a list of note paths)
obsidian vault=blog search query="Obsidian" limit=3
# Read a note
obsidian vault=blog read path="posts/202610012001.md"
# List tags sorted by usage count
obsidian vault=blog tags counts sort=count- Targeting a vault —
vault=namegoes first. If your terminal's current directory is inside a vault, that vault is used and you can leave it out. - Targeting a file —
file=resolves by name like a wikilink, andpath=takes the exact path from the vault root.
There are also commands like backlinks, tasks, and property:read. create and append exist for making and extending notes, but it's safer to let the agent use only read commands at first.
When you see "Your Obsidian installer is out of date"#
If the app is current but the installer is old, this message appears on every command.
Your Obsidian installer is out of date. Please download the latest installer which includes better CLI support: https://obsidian.md/downloadObsidian updates itself, so the app version and the installer version are tracked separately. obsidian version shows both, like 1.15.1 (installer 1.8.4). The read commands above still worked with the warning, but the right fix is what the docs require: download a fresh installer from the download page and install it. After I reinstalled, the version read 1.15.1 (installer 1.15.1) and the warning was gone.
Once connected, use notes as work orders#
At this point the agent can read the vault, knows the rules, and can't easily wreck anything. What's left is deciding what to write in a note before you hand it over.
- The format for putting one task in one note is in Using Obsidian Notes as Work Orders for AI Agents.
- How to split an idea note into issues the size of one PR is in AI Agent Workflow: Break an Idea into Issues with Completion Criteria.
- If you're tempted to watch notes and run agents automatically, read What to Get Right When Automating AI Agent Work with Markdown first. It's the record I left after building and running that myself.
Start with one folder and one rules file#
You don't need everything at once. Today, make one Git commit in your vault, create an AGENTS.md at the vault root, and write only the structure and the don'ts. Then ask the agent a read-only question. You'll see whether you need the skills or the CLI next.
If you do what you've always done, you'll get what youve always gotten.
— Tony Robbins


