vault-doctor
v0.0.1
Published
Obsidian vault health diagnostics and auto-remediation CLI
Maintainers
Readme
vault-doctor
Find and fix Obsidian vault problems before they break your notes
vault-doctor scans your Obsidian vault for broken wikilinks, malformed frontmatter, missing tags, orphan files, and stale markers — then auto-fixes what it can.
Quick Start
npm install -g vault-doctor
vault-doctor scan /path/to/vault # check vault healthUsage
Scan
vault-doctor scan /path/to/vault
vault-doctor scan /path/to/vault --json
vault-doctor scan /path/to/vault --severity high
vault-doctor scan /path/to/vault --format compactFix
vault-doctor fix /path/to/vault # auto-fix issues
vault-doctor fix /path/to/vault --dry-run # preview without writingWhat it checks
| Check | Severity | Auto-fix |
|-------|----------|----------|
| Malformed YAML frontmatter | critical | Yes |
| Missing frontmatter | medium | Yes |
| Tag conflicts (mutually exclusive pairs) | high | Yes |
| Missing layer tags (layer/raw, layer/wiki) | medium | Yes |
| Missing created date on wiki notes | low | Yes |
| Broken wikilinks | medium | No |
| Orphan files (no inbound links) | low | No |
| Stale markers (DRAFT, OUTDATED, etc.) | low | No |
Comparison
| | vault-doctor | obsidian-linter | lkits wikilinks checker |
|-|-------------|----------------|------------------------|
| Broken wikilinks | ✅ | ❌ | ✅ |
| Frontmatter repair | ✅ auto-fix | ✅ rules-based | ❌ |
| Tag conflict detection | ✅ | ✅ | ❌ |
| Orphan detection | ✅ | ❌ | ❌ |
| CLI / scriptable | ✅ headless | ❌ plugin only | ❌ plugin only |
| Config file | ✅ vault-doctor.json | ✅ plugin settings | ✅ plugin settings |
Configuration
Create vault-doctor.json in your vault root:
{
"excludeDirs": [".obsidian", ".git", ".alcove", "_template"],
"layers": {
"raw": ["99-Archives", "00-Inbox", "02-Areas", "03-Resources"],
"wiki": ["10-Zettelkasten"]
},
"requiredTags": {
"raw": ["layer/raw"],
"wiki": ["layer/wiki"]
},
"mutuallyExclusiveTags": [
["status/seed", "status/evergreen"],
["layer/raw", "layer/wiki"]
],
"staleMarkers": ["DRAFT", "OUTDATED", "DEPRECATED", "DO NOT USE"]
}Defaults work for Karpathy 3-layer (Raw/Wiki/Graph) vaults with PARA structure.
Troubleshooting
Make sure npm global bin is in your PATH:
npm config get prefix
# Add <prefix>/bin to your PATHStart with high-severity only:
vault-doctor scan /path/to/vault --severity highContributing
See CONTRIBUTING.md. PRs welcome — check open issues labeled good first issue.
License
Apache-2.0 © 2026 epicsagas
