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.
- Broken Links — Detect wiki links, markdown links, and embeds pointing to non-existent notes or headings.
- Orphan Attachments — Find images, PDFs, audio/video, and archives not referenced by any note.
- Empty Notes — Flag notes with no meaningful content beyond frontmatter and title.
- External Links — Optionally check external URLs for availability (HTTP status).
- Duplicate Files — Identify duplicates by name, size, and optional SHA-256 content hash.
- Frontmatter Types — Report properties used with inconsistent value types across notes.
- Tag Usage — Watch for missing or underused tags from a configurable watchlist.
- Large Files — Flag Markdown files and attachments exceeding configurable size thresholds.
- Scan Progress — Show scanner progress in Obsidian and optional CLI progress on stderr.
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 npm package also includes a read-only terminal scanner for local vaults, automation, and CI workflows:
npx vault-inspector /path/to/your/vaultOr install it globally:
npm install -g vault-inspector
vinspect /path/to/your/vaultThe Obsidian Community Plugin release assets contain only the in-app plugin
files. The npm package additionally includes cli.js and exposes the
vault-inspector and vinspect commands. Starting with 0.4.10, the npm
package is the supported CLI distribution path again.
Vault Inspector includes a read-only Agent Skill for CLI-based vault checks:
gh skill install rogerdigital/vault-inspector vault-inspectorIt can also be installed with the skills CLI:
npx skills add rogerdigital/vault-inspector --skill vault-inspectorThe skill teaches agents to run scans, interpret JSON/Markdown output, use baselines, and avoid modifying vault files.
- Open the command palette and run Vault Inspector: Run scan.
- The Inspector view opens in the right sidebar.
- Filter results by scanner or severity. Click paths, URLs, targets, properties, or tags to jump to the relevant location.
- Click Select to enter selection mode, then batch delete or ignore issues.
- Expand Ignored items at the bottom to restore previously ignored issues.
- Run Vault Inspector: Export report to save results as Markdown.
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.
Vault Inspector also exposes a read-only CLI for generated or agent-managed vaults.
Scan a vault:
vinspect /path/to/your/vaultFrom inside a vault, . means the current directory:
cd /path/to/your/vault
vinspect .The full command also remains available:
vault-inspector /path/to/your/vaultPin a specific npm version when repeatability matters:
npx vault-inspector@0.4.11 /path/to/your/vaultvault-inspector scan /path/to/vault is also supported for scripts that prefer
an explicit subcommand.
The default output format is JSON. It includes summary counts, scanners run, issues, ignored issues, fingerprints, evidence, and available fix-action metadata so other tools can decide what to do next.
Common options:
vinspect . --format markdown --output report.md
vinspect . --scanner broken-links,empty-notes
vinspect . --scanner external-links
vinspect . --progress
vinspect . --config vault-inspector.config.json--progress writes scanner progress to stderr so JSON and Markdown output on
stdout remain machine-readable.
For CI baseline checks:
vinspect . --baseline .vault-inspector-baseline.json --fail-on newConfig files are JSON and use the same option names:
{
"scanners": ["broken-links", "empty-notes", "large-files"],
"severity": ["error", "warning"],
"include": ["notes/**"],
"exclude": ["templates/**"],
"ignoredFolders": [".trash"],
"failOn": "warning",
"largeMarkdownBytes": 102400
}CLI flags override config file values.
Settings omitted from a config file fall back to the plugin defaults — for
example, ignoredLargeMarkdownFrontmatterKeys already defaults to
["excalidraw-plugin"], so Excalidraw drawings are ignored without any config.
If your config lists the older "excalidraw" key, update it to
"excalidraw-plugin".
JSON output has a stable top-level protocol for automation:
schemaVersion— currently1tool— alwaysvault-inspectortoolVersion— package versionsummary— stable counts and scanner metadataissues/ignoredIssues— issue records with stablescannerId,severity,primaryPath,relatedPaths,evidence,fingerprint, andfixActionfieldsgeneratedAt,durationMs, titles, and messages are informational and should not be used as stable identifiers
Baseline comparison uses issue fingerprint values from a previous JSON report.
When --baseline is provided, each issue includes isNew, and summary.newIssues
counts issues not found in the baseline.
Exit codes:
0— scan completed and did not match the configured--fail-onthreshold.1— scan completed and matched the configured--fail-onthreshold.2— invalid CLI usage or scan setup failure.
--fail-on accepts any (default), warning, error, new, and none.
CLI scan mode is read-only. --fix is reserved for a future explicit opt-in fix
command and currently exits with an error instead of modifying files.
The CLI and the Obsidian plugin share scanner logic, but they are different runtimes. The Obsidian plugin uses Obsidian metadata and UI actions; the CLI uses a local filesystem adapter and is intended for terminal, CI, and automation workflows.
Supports wiki links ([[Note]]), aliased links ([[Note|Display]]), heading links ([[Note#Section]]), markdown links, and embeds (![[image.png]]).
error— unresolved link targetwarning— missing heading in existing note
Scans for attachment files not referenced by any Markdown file.
warning— unreferenced file older than 24 hoursinfo— unreferenced file modified within 24 hours- Supported: png, jpg, jpeg, gif, webp, svg, pdf, mp3, mp4, wav, mov, zip
Flags notes that have no content beyond frontmatter and a title heading.
warning— empty note
Opt-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 status 400 or higherinfo— timed out, failed, or skipped URL checks- Checks Markdown links, frontmatter links, images/embeds, and bare HTTP/HTTPS URLs in note bodies.
Groups files by basename + extension, then by size. Files below the hash cap are verified with SHA-256.
warning— hash-identical filesinfo— same-name or same-size candidates without hash
Reports keys used with incompatible value types across notes.
warning— incompatible types (e.g., string vs array)info— string vs date-like ambiguity
Reports watched tags not present in the vault, and tags below a usage threshold.
info— all tag issues
Flags files exceeding configurable size thresholds.
warning— file above threshold- Markdown files with configured frontmatter keys, such as Excalidraw files, can be excluded from this scanner.
Excalidraw 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.
| 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 |
| 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 |
| Ignored folders | (none) | Folders excluded from all scans |
| Ignored properties | (none) | Frontmatter properties excluded from type checks |
| Report folder | Vault Inspector Reports | Folder for exported Markdown reports |
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; in the CLI it uses HTTP HEAD requests through the runtime fetch API. 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.
- Read-only — does not modify, move, or delete vault files (except exported reports and optional batch-delete via trash).
- Broken link detection relies on Obsidian's metadata cache; links inside code blocks or comments may be missed.
- External link checks are opt-in and network-dependent; timeouts or blocked requests do not necessarily mean a URL is dead.
- Orphan detection cannot account for references from CSS, Canvas, Dataview queries, or external tools.
- Duplicate detection above the hash cap reports candidates only (no content verification).
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