rogerdigital8k downloadsScan your vault for maintenance problems: broken links, orphan attachments, duplicate files, frontmatter inconsistencies, unused tags, and large files.
Scan your Obsidian vault for maintenance problems: broken links, missing attachments, orphan files, duplicate files, empty notes, tag issues, and large files.
Use it before publishing, exporting, migrating, or cleaning up a long-lived vault.

Supports wiki links ([[Note]]), aliased links ([[Note|Display]]), heading links ([[Note#Section]]), block links ([[Note#^block-id]]), markdown links, and embeds (![[image.png]]). Same-note references such as [[#Section]] and [[#^block-id]] are checked against the current note.
error — unresolved link targetwarning — missing heading or block in an existing noteDetection uses Obsidian's metadata cache. Automatic link removal only edits parsed source ranges, preserving code blocks, comments, and escaped examples. Syntax that cannot be safely identified is left unchanged.
Scans for attachment files without indexed references from Markdown links, embeds, frontmatter links, Canvas file nodes, or Canvas group backgrounds.
warning — unreferenced file older than 24 hoursinfo — unreferenced file modified within 24 hoursOrphan detection cannot account for references from CSS, dynamic Dataview queries, or external tools. Missing Markdown metadata and malformed or unreadable Canvas files reduce reference coverage; trash actions are blocked while reference coverage is incomplete. Orphan findings remain candidates, not proof that an attachment is unused.
Flags notes that have no content beyond frontmatter and a title heading.
warning — empty noteOpt-in scanner for checking HTTP/HTTPS URLs found in notes for availability. It is disabled by default because it makes network requests and depends on external sites, DNS, and rate limits.
warning — HTTP 404/410 (and other 4xx) dead-link candidatesinfo — 401/403 access-restricted, 429 rate-limited, 5xx server errors, and timed-out, failed, blocked, or skipped checksCollects candidates using two independent groups: matching basename plus extension, and matching byte size. Candidate files at or below the hash cap are verified with SHA-256, so identical content can be detected across different filenames. Files above the cap remain unverified candidates.
warning — hash-identical filesinfo — same-name or same-size candidates without hashDeletion is offered only for files confirmed identical by content hash. By default, Vault Inspector asks which file to keep. Automatic selection prefers the copy with the highest indexed inbound reference count; ties use the lexicographically smallest vault-relative path. Groups with multiple referenced copies require an explicit keep choice and are excluded from bulk actions. References are never rewritten automatically. Modification time, access time, and file size do not choose the keep file.
Duplicate detection above the hash cap reports candidates only (no content verification).
Reports keys used with incompatible value types across notes.
warning — incompatible types (e.g., string vs array)info — string vs date-like ambiguityReports watched tags not present in the vault, and tags below a usage threshold. Hierarchical tags are treated as a tree: a parent tag is only low-usage when its whole branch is below the threshold, and a watched parent counts as present when any child tag appears.
info — all tag issuesFlags files exceeding configurable size thresholds.
warning — file above thresholdExcalidraw Markdown files are ignored by default when they include the
excalidraw-plugin frontmatter key. If your vault uses filename-based Excalidraw
files without that frontmatter, add a path pattern such as
**/*.excalidraw.md to Ignored large Markdown path patterns.
You can use the same path patterns for other generated or workflow-specific
Markdown files, for example index/**/*.md or exports/**/*.md.
Search Vault Inspector in Obsidian → Settings → Community plugins → Browse.
Download main.js, manifest.json, and styles.css from the latest release and place them in .obsidian/plugins/vault-inspector/.
The core workflow is: run a scan, review new findings, then fix or ignore each one.
Scan results are selectable for copying. Duplicate file results show each file
separately, tag results show #tag chips, and exported Markdown reports include
scanner-specific detail fields.
Plugin exports measure the complete Markdown output before writing into the vault. Reports larger than 1 MiB require an explicit choice because large Markdown files may make Obsidian unresponsive while indexing. Summary exports keep scan totals and per-scanner counts but omit per-finding details. This in-vault protection does not change CLI Markdown output.
Each finding carries a confidence label — Confirmed, Needs review, or Could not verify — and a plain-language explanation: why it was reported, an optional caveat, and a suggested next step. Raw evidence remains available separately for deeper inspection.
Lifecycle comparison is available only after a successful scan and only when the previous successful scan used the same detection profile. The first successful scan establishes a baseline; changing detection settings or scanner semantics also establishes a new baseline instead of marking every finding as new. Ignoring a finding does not resolve it: ignored findings remain part of the active lifecycle comparison. Resolved rows are read-only historical records from the previous compatible snapshot, not current findings or proof that an action fixed them.
Vault Inspector is read-only by design: scans never modify, move, or delete vault files. The only writes are exported Markdown reports and fixes you explicitly confirm.
Fixes run only after explicit confirmation. Before anything happens, a confirmation dialog lists every planned fix and its impact — the files it will move to trash, the link text it will remove, and the references around them.
Each fix is preflight-checked against a fresh scan of the affected files:
After you confirm, every attempted fix is verified against fresh scan data and reported as Fixed, Still present, Skipped, or Failed. Fix results remain visible until dismissed.
Fix actions can be turned off entirely in settings. Batch delete moves files to Obsidian's trash; it never permanently deletes them.
| Setting | Default | Description |
|---|---|---|
| Enabled Scanners | All local scanners on; External Links off | Toggle individual scanners |
| Enable fix actions | On | Allow batch delete of fixable issues |
| Duplicate file keep mode | Always ask | Require a keep-file choice, or automatically keep the most-referenced copy (ties: alphabetically first) |
| Large Markdown threshold | 100 KB | Markdown files above this size are flagged |
| Large attachment threshold | 5 MB | Attachments above this size are flagged |
| Ignored large Markdown frontmatter keys | excalidraw-plugin | Markdown files with these frontmatter keys are excluded from large file checks |
| Ignored large Markdown path patterns | (none) | Vault-relative glob patterns excluded from large Markdown checks |
| Duplicate hash cap | 1 MB | Max file size for content hash comparison |
| Empty note word threshold | 5 | Notes with fewer words (excluding frontmatter/title) are flagged |
| Watched tags | (none) | Tags to watch for missing usage |
| Low usage tag threshold | 2 | Tags below this count are flagged |
| Scan exclusions | (none) | Folder or tag rules applied to all or selected scanners |
| Ignored properties | (none) | Frontmatter properties excluded from type checks |
| Report folder | Vault Inspector Reports | Folder for exported Markdown reports |
Automatic scans and network access are disabled by default: scans run only when you start them, and the External Links scanner is opt-in. If a fix reports that metadata synchronization did not complete, changes may still have been saved — run another scan and review the result before retrying.
Use Scan exclusions to add a folder or tag and choose All checks or selected scanners. Matching rules are additive: any matching rule excludes a file from the selected checks. Existing global and scanner-specific folder settings appear in this list automatically; editing them preserves their scope.
Prefer tag rules when an exclusion should follow a note, such as clipped articles or intentional drafts. The tag is visible in the note's frontmatter or body, and the rule continues to match if you move the note to another folder in the vault, as long as the tag remains. Use folder rules when the exclusion belongs to a whole directory, such as templates or an archive.
Tags match both frontmatter tags and inline #tags, case-insensitively. Enter them with or without
#; excluding clippings also excludes clippings/web, but not
clippings-other. For Web Clipper notes, apply a clippings rule only to Broken
Links to retain other checks, or choose all checks to exclude the notes broadly.
Tag rules apply to notes, not automatically to their attachments.
Excluded notes remain valid link targets and reference sources. Their attachments are still protected from false orphan reports. Duplicate groups, frontmatter consistency, and tag usage are computed within each scanner's participating scope. Excluding notes can therefore change findings for other participating notes.
After a scan, expand Scan exclusions in the results to see excluded file counts by scanner. Counts overlap between scanners and should not be added; Files scanned remains the total vault file count before exclusions. Exclusions change the scan scope, whereas ignoring a finding hides that specific result. Changing rules restarts baseline comparison, so excluded findings are not reported as resolved. Upgrading from an older scan-profile format may also restart comparison.
The same scanner logic is available as a read-only terminal scanner for local vaults, automation, and CI workflows:
npx vault-inspector /path/to/your/vault
Or install it globally:
npm install -g vault-inspector
vinspect /path/to/your/vault
CLI scan mode is read-only: it never modifies, moves, or deletes vault files. For all flags, configuration, the JSON protocol, baseline comparison, and exit codes, read the CLI reference.
Vault Inspector does not make network requests unless the External Links scanner is enabled. That scanner checks URLs you explicitly have in your notes. In Obsidian this uses Obsidian's requestUrl; the CLI uses Node's HTTP/HTTPS transport, starting with HEAD and retrying with a one-byte Range GET when the server rejects HEAD with 405 or 501. No vault content leaves your device beyond those link-check requests.
Vault Inspector enumerates vault files and Markdown metadata so scanners can detect broken links, orphan attachments, duplicate files, large files, tag usage, and frontmatter type drift. This access is local and read-only during scans.
npm install
npm run dev # watch mode
npm run lint # eslint
npm run lint:obsidian-warnings # Obsidian review warning checks
npm run build # production build
npm test # unit tests
npm pack --dry-run # inspect npm package contents, including cli.js