obsidian-health — Claude Code command: vault diagnostics
obsidian-health scans your Obsidian vault for contradictions, concept gaps, stale claims, and structural issues. Reports findings grouped by severity and spins up specialized agents to triage each category.
MIT ★ 5,412 updated 2026-10-24
/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brainWhat obsidian-health does
The command reads _CLAUDE.md to locate your vault, runs vault_health.py, and dispatches parallel subagents—one for each problem class. Each handles wanted notes (sorted by mention frequency), duplicates, frontmatter gaps, overdue tasks, orphaned notes, contradictions in Key Decisions, and typed-edge errors.
For large or noisy vaults, create a .vault-config.json to exclude directories or path prefixes (the excludes are additive with built-in ones). The scan also surfaces source problems: notes declaring local capture but holding no text; knowledge resting only on URL records; sources without a quality grade. If your vault has _meta/taxonomy.md, it validates tags against the canonical taxonomy.
This is built for wiki-style vaults where wanted notes are not errors but a ranked backlog of what to write. You can triage them manually or run triage_links.py to auto-rank by reference count (requires ANTHROPIC_API_KEY). Typed-edge linting checks for asymmetric relation contradictions.
What it helps with
- detect contradictions in key decisions and reference notes
- find missing notes based on outbound links throughout the vault
- surface sources with incomplete local capture
- validate tags against a curated taxonomy
- identify stale tasks and empty folders
Example prompts for the agent
- Run a vault audit: which notes should exist, where are the contradictions?
- Check knowledge health: do sources have quality grades assigned?
- Find duplicate concepts and errors in the typed-edge graph
How to install obsidian-health
1Plugin marketplace
/plugin marketplace add eugeniughelbur/obsidian-second-brain/plugin install obsidian-second-brain@obsidian-second-brain2Manually: put the files in place
.claude/commands/obsidian-health.mdCall it with /obsidian-health. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/obsidian-health.mdCall it with /prompts:obsidian-health. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/obsidian-health.prompt.mdManually: put the files in place
.gemini/commands/obsidian-health.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about obsidian-health
How do I install obsidian-health in Claude Code?
Run /plugin marketplace add eugeniughelbur/obsidian-second-brain, then /plugin install obsidian-second-brain@obsidian-second-brain, and ensure .claude/commands/obsidian-health.md is available in your project.
What does obsidian-health do?
It scans your vault for contradictions, concept gaps, stale data, and structural issues across sources, frontmatter, relations, and tags. Results are bucketed by severity, and subagents handle each category in parallel.
What do I need to run it?
uv to execute Python scripts, and your vault path from _CLAUDE.md. To auto-rank wanted notes via triage_links.py, set ANTHROPIC_API_KEY.
Source text
obsidian-health.md · MIT
---
description: Run a vault health check - grouped by severity, detects contradictions, concept gaps, stale claims, and structural issues
category: meta
triggers_en: ["vault health", "check vault", "audit vault", "vault diagnostics"]
triggers_de: ["Vault-Gesundheit", "Vault prüfen", "Vault auditieren", "Vault-Diagnose"]
triggers_es: ["salud del vault", "revisa el vault", "audita el vault", "diagnóstico del vault"]
triggers_pt: ["saúde do vault", "verifique o vault", "audite o vault", "diagnóstico do vault"]
triggers_zh: ["检查知识库健康状况", "给我的知识库做体检", "审计我的笔记库", "诊断知识库问题"]
---
Use the obsidian-second-brain skill. Execute `/obsidian-health`:
1. Read `_CLAUDE.md` first to find the vault path
2. Run the health scan from the skill root (its absolute path was given at session start as **Skill root**; substitute it for `SKILL_ROOT`): `uv run --directory "SKILL_ROOT" scripts/vault_health.py --path ~/path/to/vault --json`
(replace vault path with the one from `_CLAUDE.md`)
- **Large or noisy vault?** If the scan surfaces thousands of findings from directories the user does not maintain by hand (atomic-card pools, backup snapshots, imported dumps), do NOT hardcode fixes. Offer to write a `<vault>/.vault-config.json` that extends the exclude list: `{"exclude-dirs": ["_card-pool"], "exclude-paths": ["Archive/Backup"]}`. `exclude-dirs` matches directory names anywhere in the tree; `exclude-paths` matches vault-relative path prefixes. Both are additive - the built-in excludes always apply - and a missing or malformed file is ignored silently. Re-run the scan afterward.
- **`source_payload` findings?** (#194) Three different problems under one type. An `error` naming one source means the note declares `capture_scope: full-local` or `bounded-local` and has essentially no body - it claims evidence it does not hold, so re-capture it or set `capture_scope: url-only` and say so plainly. A `warning` naming a source plus the notes that link it means active knowledge rests on a `url-only` record: the vault kept the locator, not the evidence. Offer to re-capture the source, or to mark the dependent claims as URL-backed; never resolve it by copying a complete copyrighted work. The single `info` line counting sources with no `capture_scope` is every source written before the field existed - fill them in as you touch them, do not sweep the vault. `"source_policy": "strict-local"` in `.vault-config.json` raises the last two by one severity.
- **`source_quality` findings?** (#258) A `warning` names a concept, synthesis or other note that cites only sources graded `speculation`: provenance unknown, derived or conflicting. It is not a claim that the note is wrong. Offer to corroborate its claims with a better source (the bounded lateral read in `references/source-quality-check.md`, only on an explicit yes), or to say in the note that they are unverified. A source with no `source_quality` is unjudged and never reported. `"source_quality_policy": "silent"` in `.vault-config.json` mutes the check.
- **`source_quality_unlabelled` findings?** (#258) A `warning` names a `type: source` note whose first lines say it is unverified, unconfirmed or speculative while its frontmatter has no `source_quality`. The prose is right, the field is missing. Offer to add `source_quality: speculation`, or a higher grade if the note shows the provenance capture saw. The same policy key mutes it.
- **`rewrite_policy: unattended` info line?** The vault has opted out of the confirm-before-rewrite gate in `/obsidian-ingest` (#250) and reviews rewrites through its own layer. Nothing to fix; the line is there so a reader of the report knows the vault runs without the gate. Remove the key from `.vault-config.json` to restore the default.
3. Parse the JSON output and split findings into categories
4. Spawn parallel subagents to handle each category simultaneously:
- **Wanted-notes agent**: the script reports `wanted_note` items - links to a note that does not exist yet. These are NOT errors: in a wiki-style vault you link a thing the moment you mention it, so wanted notes are a demand-ranked wishlist of pages worth writing, not breakage. Triage them with `uv run --directory "SKILL_ROOT" scripts/triage_links.py --path <vault> --limit N`, which sorts each into keep (a deliberate seed, leave it), create (referenced enough to deserve a real note now), or delete (junk or a typo - fix the link). Report-only by default; needs `ANTHROPIC_API_KEY`. Headless on purpose: it can run unattended or on a schedule. The goal is to triage the backlog, never to drive the count to zero.
- **Duplicates agent**: confirm duplicates are truly the same concept, not just similar names
- **Taxonomy agent**: only fires when `<vault>/_meta/taxonomy.md` exists (format in `references/taxonomy-format.md`) - the script's `tag_synonym` and `tag_not_in_taxonomy` findings are empty otherwise, so a vault without the file sees nothing. `tag_synonym` means a note's tag is a known synonym of a canonical tag: the fix is unambiguous, so offer to rewrite that note's `tags:` frontmatter to the canonical form, per note, with explicit confirmation before editing - never batch-rewrite across the vault unattended. `tag_not_in_taxonomy` means the tag matches neither a canonical tag nor a synonym: report it as informational only - it may be a legitimate new tag - and never auto-fix it; the taxonomy file is a human-curated vocabulary, not something this command edits on its own.
- **Frontmatter agent**: identify notes missing required fields by type. If the script reports a `code_fence_wrapped` note (frontmatter trapped inside a leading ```` ```markdown ```` fence), the fix is to **unwrap it** - strip the opening fence line and the matching closing ```` ``` ```` so the inner `---` frontmatter and body become real markdown. **Never add a new frontmatter block to a wrapped note** - that produces duplicate frontmatter and leaves the body trapped. If the note already has both a prepended frontmatter block and an inner wrapped one, merge them (keep the richer fields) and unwrap.
- **Staleness agent**: check overdue tasks and unfilled template syntax
- **Orphans agent**: check orphaned notes and empty folders
- **Contradictions agent**: scan Key Decisions sections and reference/concept notes (the concept or knowledge folder per `references/folder-map.md` - wiki-style `wiki/concepts/`, Obsidian-style `Knowledge/`) for claims that conflict with each other or have been superseded by newer sources
- **Typed-edge lint agent**: run `uv run --directory "SKILL_ROOT" scripts/link_graph.py --path <vault> --lint`, which validates the `relations:` typed-edge layer (see `references/ai-first-rules.md` Rule 6 § Typed edges). It returns `findings` (each with `severity`, `kind`, `note`, `target`, `type`, `detail`) and a `summary`. Map them into the severity groups below: `contradiction` (A and B claim the same asymmetric type about each other) is 🔴 Critical; `unknown_type`, `dangling_target`, and `self_edge` are 🟡 Warning (fix the type name, the target link, or drop the self-edge); `missing_inverse` is ⚪ Info (offer to add the reciprocal edge on the target note, never required). If the vault uses no `relations:` blocks yet, this returns zero findings - not an error.
- **Concept gaps agent**: find terms mentioned 3+ times across different notes that lack a dedicated page - these are missing concepts the vault should have
- **Stale claims agent**: compare reference/concept notes (the concept or knowledge folder per `references/folder-map.md` - wiki-style `wiki/concepts/`, Obsidian-style `Knowledge/`) against their source dates - flag any note older than 6 months that references fast-moving topics (tools, APIs, pricing, team structure)
- **Freshness agent**: run the freshness lint - `uv run --directory "SKILL_ROOT" scripts/freshness_lint.py --path <vault> --json` - which enforces `references/freshness-policy.md`: every stored fact must be timeless, dated, or a pointer. FRESH-1 errors are present-tense claims about fast facts (counts, statuses, balances) with no `as of` stamp - the sentences that silently become lies. Report the top offenders grouped by folder; offer to fix by adding a stamp, converting to a pointer (where truth lives + last observed value), or moving the claim into a dated note. For aged stamps (FRESH-2 warnings) run the refresh loop from the policy: re-observe (check the source, update value + stamp), convert (keep only the pointer), or retire (move into a dated note as history). Never delete - restamp, convert, or mark superseded
5. Merge results and group by severity:
- 🔴 Critical: unfilled template syntax, contradictions between notes, typed-edge contradiction cycles, code-fence-wrapped notes (frontmatter trapped in a fence)
- 🟡 Warning: duplicates, stale tasks, missing frontmatter, stale claims, concept gaps, freshness violations (undated fast facts, aged stamps), typed-edge problems (unknown type, dangling target, self-edge), tag-synonym findings (a tag that should fold to its canonical form per `_meta/taxonomy.md`), invalid tags (digits-only, dots, spaces - Obsidian renders these broken with no error; fix by prefixing a word or replacing the separator with `-`)
- ⚪ Info: wanted notes (linked but unwritten - a wishlist, not errors), orphaned notes, empty folders, missing inverse edges, tags not in the taxonomy (informational, not necessarily wrong)
6. For safe fixes (missing frontmatter, unwrapping code-fence-wrapped notes, obvious duplicates, creating pages for concept gaps), offer to fix automatically. For a `code_fence_wrapped` note, unwrap the fence rather than adding frontmatter (see the Frontmatter agent note above).
7. For destructive fixes (archiving, merging, resolving contradictions), list them and ask for explicit confirmation first
8. Append to the operation log: if `Logs/` exists write `**HH:MM** - health | X critical, Y warnings, Z info` to `Logs/YYYY-MM-DD.md`; otherwise append `## [YYYY-MM-DD] health | X critical, Y warnings, Z info` to `log.md`
---
**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md` - `## For future agent` preamble, rich frontmatter (`type`, `date`, `tags`, `ai-first: true`, plus type-specific fields), recency markers per external claim, mandatory `[[wikilinks]]` for every person/project/concept referenced, sources preserved verbatim with URLs inline, and confidence levels where applicable. If that path does not resolve from your working directory, search upward for it; if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. The vault is for future agent retrieval - not human reading.
**Anti-fabrication:** Search exhaustively before claiming any note, person, or file is absent - false absence is the most common failure mode - and never invent facts, entities, or dates (mark unknowns as `TBD`). See the anti-fabrication and search-completeness hard rules in `references/ai-first-rules.md`.
© Eugeniu Ghelbur · MIT · eugeniughelbur/obsidian-second-brain