vault-keeper

Published on npm as claude-code-vault-keeper — the vault-keeper binary is what you'll actually type.

Your vault has 1,247 notes. How many use status: done vs status: completed? How many tag with #book vs #books? How many books are missing a rating: field?

You don't know. Neither does Dataview. That's why your queries quietly lie.

Every markdown vault rots the same way

1. You start with 50 notes and a tidy convention.
2. You copy a template once, tweak it, lose track of which copy is the real one.
3. AI tools (Claude, ChatGPT, Cursor) generate notes with slightly different frontmatter than yours.
4. Six months later: tag vs tags, status: WIP vs status: in-progress, half your book notes have author:, the other half have by:.
5. Your Dataview queries quietly miss half your data. You stop trusting them.
6. You promise yourself a "cleanup pass." It never happens.

vault-keeper makes your vault enforce its own conventions. Write the rules once, in a template you control. Get a red squiggle the moment a note breaks them — in your editor, in CI, in the loop where your AI assistant writes new notes.

It works with any markdown folder: an Obsidian vault, a Logseq graph, a Foam workspace, a repo full of ADRs and RFCs, a personal Zettelkasten. The plugin contains zero domain knowledge about your notes. Your templates decide everything.

Adopting an existing vault? Don't try to convert 500 notes overnight. Set vaultFolders in .claude/vault-keeper.json to one subfolder (e.g. ["books"]), author one template, point that folder's notes at it, watch it go green. Folders outside vaultFolders are silently ignored, so the rollout is incremental — add a folder when you're ready to enforce it. See docs/vault-config.md for the config reference and examples/example/ for a working single-folder setup to copy from.

What you actually see

Two notes that drifted from your book-note template — one set status: wip where the template allows only [reading, done, abandoned], the other is missing the created: field your queries depend on:

📄 library/books/2024-shogun.md
   🚨 status: Invalid status: 'wip'
      💡 Fix: Use one of: reading, done, abandoned
   🚨 created: Missing required field: created
      💡 Fix: Add created to frontmatter

📄 library/books/atomic-habits.md
   🚨 rating: Value 0 below minimum 1 for rating
      💡 Fix: Set rating ≥ 1

📊 SUMMARY
Total Documents: 487
✅ Valid: 484/487
🚨 Errors: 3

exit 1

That same diagnostic appears inline as you type if you install the Claude Code plugin — no save, no run, no context switch.

CI fails on the first error. Reviewers stop nitpicking format and start reviewing content.

How the rules work

Rules live in your templates, not buried in the tool. A book-note template might look like this:

---
template_path: templates/book.md
document_type: book
fields:
  $path:
    pattern: "^library/books/"
  template:
    required: true
  title:
    required: true
  author:
    required: true
  created:
    required: true
    type: string
    pattern: "^\\d{4}-\\d{2}-\\d{2}$"
  status:
    required: true
    type: string
    enum: [reading, done, abandoned]
  rating:
    type: integer
    min: 1
  tags:
    type: array
  finished:
    type: string
---

# Book template

Body sections this template expects.

## Takeaways

## Quotes

Edit the template. Every note that declares template: templates/book.md revalidates against the new rules — no rebuild, no code change. The full rule vocabulary covers composable field primitives (type, enum, pattern, required, min/max, uniqueItems, exists), conditional requirements via a small DSL (and, or, in, not in), body section-rules (heading patterns, table/list/code validation, repeatable headings, formula expressions), and strict mode for undeclared-field detection.

Try it in 30 seconds

# 1. Scaffold a sample vault (no install)
bunx -p claude-code-vault-keeper vault-keeper init my-vault
cd my-vault

# 2. Look at templates/note-template.md — those are the rules
# 3. Validate
bunx -p claude-code-vault-keeper vault-keeper validate
# → Valid: 1/1, exit 0

# 4. Break notes/note-001-hello.md (e.g. delete `owner:`)
bunx -p claude-code-vault-keeper vault-keeper validate
# → exit 1, explains exactly what broke and how to fix it

For per-keystroke diagnostics in your editor, install the Claude Code plugin. The vault-keeper CLI ships a one-liner wrapper:

vault-keeper install-claude-code-plugin

Or, if you don't have the CLI on $PATH (or just prefer to see what's happening), run the two claude commands yourself:

claude plugin marketplace add https://github.com/nguyenvanduocit/claude-code-vault-keeper.git
claude plugin install claude-code-vault-keeper@vault-keeper

That's it. Open any .md in your vault and the LSP highlights problems live.

Who this is for

• Obsidian / Logseq / Foam users with vaults large enough that you can't manually keep them consistent. You have templates but no way to make notes honor them. You'd love to know which 12 notes are missing a created: field without writing your own script.
• Note-takers using AI assistants. Claude, ChatGPT, Cursor, Copilot cheerfully generate notes that drift from your conventions. Wire vault-keeper validate into the AI's loop (or its post-write hook) and it self-corrects from the same diagnostics you'd read — instead of silently drifting your vault.
• Teams maintaining ADRs / RFCs / PRDs in markdown. Reviews waste time on "where's the decision: field" comments. CI doesn't gate format. vault-keeper exit codes plug into any CI runner.
• Anyone whose markdown collection has crossed the threshold from "I know what's in here" to "I hope it's in here somewhere."

Install

| Path | When | Command | |---|---|---| | One-shot | Trying it out, one-off CI check. | bunx -p claude-code-vault-keeper vault-keeper <cmd> | | Global | Many vaults; want vault-keeper on $PATH. | bun add -g claude-code-vault-keeper | | Project dev-dep | Vault lives inside a JS/TS repo. | bun add -D claude-code-vault-keeper | | Claude Code plugin | Inline LSP diagnostics in your editor. | vault-keeper install-claude-code-plugin |

npm / npx work everywhere bun / bunx do — no bun runtime required. Node ≥ 18.

What's in the box

• CLI (vault-keeper) — validate, doctor, init, install-claude-code-plugin. Exit codes wired for CI.
• LSP server — diagnostics, hover, completion, code-action, code-lens, rename, document formatting. Pre-built bundle, no install step for editor diagnostics.
• Composable schema engine — the same validation primitives drive editor and CI. What passes locally passes in CI; no "works on my machine."
• Public programmatic API — import { applyFieldSchema, applyBodySchema, validateDocument, loadTemplateRules, formatVaultDocument, … } from 'claude-code-vault-keeper'. Reuse the same primitives the CLI and LSP build on to write custom reporters, dashboards, CI gates, pre-commit hooks, or editor integrations. See docs/programmatic-usage.md.
• No domain knowledge. Every rule comes from a template you wrote. Drop vault-keeper into any markdown folder and it adapts.
• Eight Claude Code skills — verbs you type in a Claude session: /vault.setup (onboarding), /vault.new <type> (scaffold doc), /vault.health (read-only report), /vault.fix (auto-format), /vault.changelog (remote changelog), /vault.sync (validate-then-push), /vault.monitor-git-sync (passive watcher), /vault.help (overview + doc links). See skills/README.md.

Documentation

• Getting started — install + first vault, 5 min.
• Templates — author rules your vault enforces.
• CLI reference — every flag, every exit code.
• LSP features — what each editor surface does.
• Programmatic usage — import { applyFieldSchema, validateDocument, … } from 'claude-code-vault-keeper' for custom scripts, dashboards, CI gates, and editor integrations.
• CI/CD integration — GitHub Actions / GitLab / generic Bash.
• Vault config — .claude/vault-keeper.json reference.
• Troubleshooting — concrete fixes for common errors.

A self-contained reference vault that exercises every rule kind lives at examples/example/ — copy-paste from it.

Repo

Source: https://github.com/nguyenvanduocit/claude-code-vault-keeper Issues: https://github.com/nguyenvanduocit/claude-code-vault-keeper/issues Releasing: see docs/releasing.md.

Cloning is for contributors. End users install via bunx / npx / bun add / npm i.

License

MIT — see LICENSE.