Vault Inspector: find broken links and orphan attachments

Share & showcase Plugins
1

Plugin/Theme Disclaimer

Is this project open source? Yes
Is this project completely free? Yes
Is this project vibe-coded beyond the author’s ability to comprehend how it works? No
Community Directory: https://community.obsidian.md/plugins/vault-inspector

Hi everyone, I built Vault Inspector, an open-source Obsidian community plugin for checking vault health and cleanup issues.

The workflow I wanted to improve is vault maintenance. In older or larger vaults, it is easy to accumulate broken links, moved attachments, orphan files, empty notes, and duplicate candidates without noticing.

Vault Inspector scans for:

  • Broken links.
  • Missing attachments.
  • Orphan attachments and other orphan files.
  • Duplicate file candidates.
  • Empty notes.
  • Tag usage issues.

GitHub repository: https://github.com/rogerdigital/vault-inspector

I would appreciate feedback from people who maintain large or long-lived vaults, especially around scanner types, severity levels, and cleanup workflows.

2 Likes
2

Small update: Vault Inspector 0.4.3 is out.

What changed:

  • Fixed short wiki-linked attachments such as ![[image.png]] being treated as missing when the actual file lives in an attachment folder like attachments/image.png.
  • Fixed referenced wiki-linked images being reported as orphan attachments.
  • Added vinspect as a shorter CLI command, while keeping vault-inspector available.
  • Simplified the README CLI examples around the common scan path.
  • Clarified how CLI external-link checks work.

Release notes:

I’m especially interested in feedback from people with larger vaults or non-standard attachment folder setups, since those cases help improve the scanner behavior.

3

Small update: Vault Inspector 0.4.4 is out.

Vault Inspector scan results

What changed:

  • Added scan progress in the Obsidian sidebar.
  • Added optional CLI progress with --progress; progress goes to stderr so JSON/Markdown output stays machine-readable.
  • Improved result navigation: paths, URLs, broken-link targets, frontmatter properties, and tags can now jump to the relevant location.
  • Improved result display for duplicate files and tag usage. Duplicate file candidates now show each file separately, and tag issues show #tag chips.
  • Scan result text can be selected and copied.
  • External link checks now also detect bare HTTP/HTTPS URLs in note bodies. External Links remains opt-in by default.
  • Markdown reports now include scanner-specific details.
  • Scan durations now use millisecond, second, or minute units depending on the actual runtime.

Links:

I’m especially interested in feedback on result navigation, duplicate-file display, and larger vault scan behavior.

4

Small update: Vault Inspector 0.4.10 is out.

This release is mostly maintenance work since 0.4.4, but there are a couple of user-facing changes.

What changed:

  • Large Files can now ignore generated Markdown files more cleanly. Excalidraw Markdown files are ignored by default when they have the excalidraw frontmatter key, and there are settings for ignored frontmatter keys and vault-relative path patterns such as **/*.excalidraw.md, index/**/*.md, or exports/**/*.md.
  • The npm CLI is available again in 0.4.10. Both vault-inspector and vinspect work for terminal/CI scans, with JSON or Markdown output.
  • The Obsidian plugin release and npm package are split more cleanly now: the Community Plugin release only ships main.js, manifest.json, and styles.css; the npm package also includes cli.js.
  • External link checks in Obsidian use Obsidian’s request API; the CLI uses the runtime fetch adapter.
  • Added stricter Obsidian warning checks, fixed CSS compatibility warnings, moved CI/release to Node 24, and added package dry-run checks so CLI packaging regressions are caught before merge.

Links:

I’d be interested in feedback on two areas: whether the Large Files scanner behaves better around generated Markdown files, and whether the CLI is useful for CI or automated vault checks.

5

Vault Inspector 0.4.11 is now available.

Main update: a new Agent Skill for Vault Inspector. It gives coding agents a read-only workflow for scanning Obsidian vaults with the CLI, reading JSON/Markdown output, using baselines, and avoiding unintended vault changes.

Install:

gh skill install rogerdigital/vault-inspector vault-inspector

Also included: better Unicode support for CLI tags and broken-link heading checks.

Release:

6

Small maintenance update: Vault Inspector 0.4.13 is out.

What changed since 0.4.11:

  • Fixed the default Excalidraw frontmatter key used by the Large Files scanner. Vault Inspector now ignores Excalidraw Markdown files with the actual excalidraw-plugin key by default, and existing settings using the older excalidraw key are migrated automatically.
  • Moved the CLI source outside the plugin src/ tree so the Obsidian community review checks do not flag Node.js APIs that are only used by the CLI.
  • Fixed a review-validation issue around an eslint-disable comment.

Release notes:

7

Small maintenance update. Vault Inspector 0.4.14 is now available.

This release makes cleanup safer and scanning more accurate. Broken-link fixes now remove only the exact wiki-link token. Links inside code and comments are ignored. Each fix is checked again before it runs. Markdown links that cannot be changed safely remain report-only.

Link and attachment resolution now handles source-relative paths and frontmatter references more consistently. The CLI also follows Obsidian metadata behavior more closely. It skips hidden directories and cleanly cancels external-link requests that time out. Large-file issue fingerprints now remain stable when file sizes change.

Release notes

CLI package
www.npmjs.com/package/vault-inspector

Feedback on the safer fix flow or CLI behavior is welcome.

8

Environment

  • Operating system: Windows 10

  • Obsidian version: [insert version]

  • Vault Inspector version: [insert version]

  • Vault size: approximately 10,000 files

  • Vault location: D:\Obsidian

Problem

Large Markdown reports exported by Vault Inspector cause Obsidian to display a black screen while indexing the vault.

The problem disappears when the reports are moved outside the vault.

Affected reports

Three exported reports were located in:

D:\Obsidian\02 Aktivt arkiv\Chatgpt Export 2026-07-22\files\Funktioner til brudte links_6a541b54\

The files were:

  • Vault Inspector Report 2026-07-12T23-13-41.md — approximately 3.2 MB

  • Vault Inspector Report 2026-07-13T13-30-05.md — approximately 3.1 MB

  • Vault Inspector Report 2026-07-13T11-16-28.md — approximately 3.1 MB

Steps and observed behaviour

  1. The three reports were present inside the vault.

  2. Obsidian started indexing the vault folders.

  3. During indexing, the entire Obsidian window turned black.

  4. I closed Obsidian and moved only the three Vault Inspector reports outside the vault.

  5. Obsidian then opened and indexed the vault normally.

  6. The black-screen problem disappeared without any other material changes.

The same problem had previously occurred when another large Vault Inspector report was stored in the vault archive.

Expected behaviour

Markdown reports exported by Vault Inspector should be able to remain inside the vault without blocking Obsidian’s indexing or causing the user interface to turn black.

If reports can become too large or structurally complex for reliable indexing, the plugin could:

  • warn the user before exporting,

  • split large reports into smaller files,

  • offer an export location outside the vault,

  • or recommend excluding the report folder from indexing.

Actual behaviour

Three reports of approximately 3.1–3.2 MB each caused Obsidian to become unusable during indexing. Moving the reports outside the vault resolved the problem.

The reports contain private file names and paths, so I have not attached them. I can provide file statistics or a sanitised excerpt if required for debugging.