Turns an Obsidian vault — a folder of Markdown notes with frontmatter, #tags, and [[wikilinks]] — into a knowledge base Claude can search and reason over. Works with any vault, on any topic: homelab documentation, project notes, research, whatever you keep in Obsidian.

What it does

Reads your vault's own structure rather than imposing one: your folders become topical categories, your tags and frontmatter become filters, your wikilinks let Claude follow related notes (backlinks) the same way you would clicking through the graph.
Answers grounded in what's actually in your notes. If the vault doesn't have an answer, Claude says so instead of guessing, and keeps general knowledge clearly separate from what came from your vault.
Optionally writes back, depending on the mode you choose at setup — from strictly read-only, to appending new dated notes, to actively updating existing ones.

Setup

After installing the plugin:

/obsidian-vault-kb:setup

This will ask you for:

The vault path(s). You can register more than one vault (e.g. a personal one and a work one) and refer to them by name.
A mode:
- read-only — Claude can search and read, never write anything.
- append — Claude can also file new findings as new, dated notes. Existing notes are never touched.
- maintain — Claude can also update existing notes directly (e.g. add a dated "Update" section, change a status field).

It also whitelists three narrow, read-only helper scripts (see below) so searching your vault doesn't require a permission prompt on every single find/grep call.

Usage

You don't need to invoke anything explicitly — just ask Claude things like:

"What did I write about the Ceph cluster rebuild?"
"Check my notes for how I set up mTLS on Postfix."
"Any open items in my homelab notes related to DNS?"

Claude recognizes references to "my notes", "my vault", "my docs", etc. and searches automatically. Under the hood it uses three scripts:

vault_index.sh — folder structure, note counts, tags, index/MOC files
vault_search.sh "<query>" — full-text search, optionally scoped to a subfolder
vault_backlinks.sh "<note-name>" — notes linking to a given note

All three resolve the vault path only from ~/.agent-skills/obsidian-vault-kb/config.json — they can't be pointed at a different directory than what you configured, which is what makes it safe to whitelist them without granting broader filesystem access.

Writing to your vault

Only relevant in append or maintain mode:

append — new findings are filed as new notes (e.g. Notes/2026-08-04-dns-fix.md), with frontmatter and wikilinks to related topics. Existing files are never modified.
maintain — Claude may extend an existing note directly instead of creating a new one, when that's the more natural place for the information. You'll always see a summary of what's about to be written before it happens.
Writing into the vault is never in the permissions whitelist, regardless of mode — every write stays a normal, visible, confirmable action.

Multiple vaults

Registered vaults live in ~/.agent-skills/obsidian-vault-kb/config.json:

{
  "vaults": [
    {"name": "homelab", "path": "/absolute/path/to/homelab-vault"},
    {"name": "worldbuilding", "path": "/absolute/path/to/tangier-vault"}
  ],
  "mode": "append"
}

If you only ever use one vault, you don't need to name it when asking Claude to search — it's used by default.

What's deliberately not included

No generic Bash(find:*), Bash(rg:*), Bash(grep:*), or Bash(cat:*) — those would allow reading anywhere on the filesystem, not just your vault.
No auto-approved writes — not to notes, not to the config file.
Binary attachments (PDFs, images) inside the vault aren't read automatically, only referenced, unless you ask for them specifically.