Disclaimer
Is this project open source? Yes, MIT: GitHub - oswarren/vault-health-check: A read-only Claude Code routine that audits your Obsidian vault: what is piling up, unlinked, and going stale. Writes one report, changes nothing. · GitHub
Is this project completely free? Yes. (A paid extended edition exists as a separate product; everything shared here is complete on its own.)
Is this project made with AI beyond the author’s ability to comprehend how it works? No. The whole routine is a plain-English Markdown file you can read top to bottom; there is no code.
I run scheduled Claude Code routines for my own systems, and the vault was the one place I still did the upkeep by hand. So I wrote a routine that audits the vault and tells me what my filing habits are actually doing: what is piling up in the Inbox, which notes nothing links to, which projects have gone quiet.
How it works. You put three files in a Night Shift folder in your vault: the routine (vault-health-check.md) and a launcher for Windows or Mac. In the routine’s settings block you describe your folders in plain sentences (“Projects: one note per thing I am actively building”). The launcher runs Claude Code headless from your vault folder; Claude reads each Inbox note, decides where it would file it and which one to three existing notes it would link it to, checks for orphan notes and stale projects, and writes a single report note into Night Shift/Reports/. Then it stops.
Why it cannot touch your notes. The launcher’s permission list grants Read, Glob, Grep, Write, and a few read-only shell commands. Edit and mv are never granted, and rm is denied outright, enforced by Claude Code itself, outside the model. The only file it can write is the report.
What the report looks like. A real one from the test vault ships in the repo, unedited; two lines from it:
[[phone note]] to Notes. A list of tomato varieties to try next year; one idea, written to keep. Would be renamed to “Tomatoes to try next year” with
phone notekept as an alias.
[[Workbench]], 45 days, three open checkboxes under “Next steps” (laminate the top, flatten it, cut the leg mortises).
Routine, launchers, and the full sample report: GitHub - oswarren/vault-health-check: A read-only Claude Code routine that audits your Obsidian vault: what is piling up, unlinked, and going stale. Writes one report, changes nothing. · GitHub
It requires Claude Code and a Claude Pro or Max subscription (install is one line at claude.ai/code); a run is a few minutes of model time. No plugin, no server, and the routine is granted no network access.
Happy to answer anything about the routine or the permission setup.