Using an Obsidian Vault as a Knowledge Base for Claude Code: What Actually Works

There Is No Official Integration — And It Works Anyway

Let's clear up a misconception first. There is no official integration between Obsidian and Claude Code. Neither Obsidian's documentation nor Anthropic's Claude Code documentation offers a dedicated connector or plugin for the other. If you're looking for an "integration module" to install, it doesn't exist.

The reason the combination works anyway is far more mundane — and therefore far more robust. An Obsidian vault is just a folder.

Obsidian's official documentation defines a vault as "a folder on your file system which contains your notes, attachments, and the configuration folder with Obsidian-specific settings." And Obsidian's homepage is explicit about storage: "Obsidian stores your notes locally as plain text Markdown files."

Claude Code, per its own documentation, is "an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools." You start it from a terminal:

cd your-project
claude

In other words, Claude Code reads and writes files in the directory it was launched from. A vault is a directory containing Markdown files. That's the whole trick. Run claude inside your vault folder and your notes are simply files it can work on. No API, no webhook, no connector required.

Pattern 1: Just Run It Inside the Vault

The simplest approach:

cd ~/Documents/MyVault
claude

Claude Code can now search, read, create, and edit the .md files in your vault. Obsidian watches for file changes and reflects them in the app, so edits made by the agent show up in your notes.

Pattern 2: Work in a Code Repo With the Vault Attached

This is the more useful pattern in practice. Your code lives in a repository; your design notes, incident write-ups, and decision logs live in a vault. Claude Code can attach directories outside its working directory:

cd ~/git/my-service
claude --add-dir ~/Documents/MyVault

Per the official docs, directories added with --add-dir follow the same permission rules as the original working directory: they become readable without prompts, and editing follows the current permission mode. Use /add-dir to attach one mid-session, or permissions.additionalDirectories in your settings file to attach one every time.

One caveat: an additional directory grants file access, but does not become a configuration root. If you want a CLAUDE.md inside the vault to be loaded too, you have to opt in:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ~/Documents/MyVault

Pattern 3: Put a CLAUDE.md at the Vault Root

Claude Code reads the CLAUDE.md in its working directory at the start of every session. If you're going to let an agent loose in your vault, this file is where you write the vault's rules: note naming conventions, frontmatter format, tag taxonomy, folders it must not touch.

The official guidance is clear: keep each file under about 200 lines, and make instructions concrete enough to verify. Instead of "keep things organized," write "daily notes go in Daily/YYYY-MM-DD.md."

As rules accumulate, split them into a .claude/rules/ directory. Each rule file can carry a paths frontmatter field so it only loads when Claude touches matching files:

---
paths:
  - "Daily/**/*.md"
---

# Daily note rules
- Frontmatter must include `date` and `tags`
- Append below existing entries; never delete them

The Limits You Must Know About

This is the real point of the article.

CLAUDE.md is not enforcement. Anthropic's documentation says so directly: CLAUDE.md files and auto memory are treated as context, not enforced configuration, and there is no guarantee of compliance. Writing "never modify this folder in my vault" into CLAUDE.md does not protect it.

To actually block something, use permission rules. Read and Edit rules follow gitignore pattern syntax and go in permissions.deny in your settings file. To keep the agent out of Obsidian's config folder:

{
  "permissions": {
    "deny": [
      "Edit(.obsidian/**)"
    ]
  }
}

Rules are evaluated deny → ask → allow, and a deny at any settings layer cannot be overridden by an allow at another. For stronger guarantees, block with a PreToolUse hook or enable sandboxing.

And put your vault under version control. What this setup really amounts to is granting an AI agent write access to your notes folder. The agent edits files directly. Make the vault a git repository and you can revert changes you don't like. That's less an option than a prerequisite.

On Third-Party Plugins

Community plugins that run Claude Code inside Obsidian do exist on GitHub (for example, deivid11/obsidian-claude-code-plugin). These are third-party projects by individual developers, not official products from Obsidian or Anthropic. Since such a tool gets access to all of your notes, review its code and maintenance status before installing.

Summary

• There is no official Obsidian ↔ Claude Code integration.
• None is needed: a vault is a folder of Markdown files, and Claude Code is a tool that operates on files in a folder.
• Run claude inside the vault, or attach the vault to a code repo with --add-dir.
• Use CLAUDE.md at the vault root for rules — but remember it is not enforcement. Real blocking is done with permissions.deny.
• Put the vault under git before you start.