claude-code-vault-keeper

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