Obsidian Graph Auditor

Obsidian Graph Auditor

Score an Obsidian vault on the 8-dimension Grade-A rubric. Read-only. Pure Python. No GPT, no API keys.

When to use this skill

Trigger this skill whenever the user wants to:

1. Audit a vault. "audit my obsidian vault", "is my obsidian healthy", "is my second brain healthy"
2. Find orphans. "find orphans in my vault", "obsidian orphans", "show me unconnected notes"
3. Diagnose a mega-hub. "is my vault a force-star?", "top-hub edge-share", "vault concentration"
4. Grade community structure. "Louvain modularity", "community detection", "are my clusters siloed?"
5. Establish a CI gate. Use --baseline to fail CI when a vault regresses.
6. Compare before/after. Run twice across a refactor to prove improvement.
7. Decide what to fix first. The rubric's worst dimension is the highest-leverage fix.

What it measures (the 8 dimensions)

A vault is Grade A only if every dimension grades A. The worst dimension is the overall grade, by design, so you always see the highest-leverage fix.

How to run

After installation (see ## Install below):

# Default: audits ./vault if present, else the current directory.
obsidian-graph-audit

# Explicit vault path with JSON dump (useful for CI).
obsidian-graph-audit --vault ~/Documents/MyVault --json-out audit.json

# CI gate: fail (exit 1) if any dimension regresses vs the baseline.
obsidian-graph-audit --vault ~/Documents/MyVault --baseline last-audit.json

# Custom thresholds for non-default styles (e.g. heavier orphan tolerance).
obsidian-graph-audit --vault ~/Documents/MyVault --threshold-config my-rubric.yaml

Default exit codes:

• 0: audit ran cleanly (and matched/exceeded baseline, if supplied)
• 1: at least one dimension regressed vs baseline
• 2: vault path missing or unreadable

How to read the output

The scorecard has 5 sections:

• STRUCTURE: total notes, edges, link density. If density < 1.5 you have a capture-heavy vault that isn't connecting.
• CONNECTIVITY: orphan + near-orphan + connected-2plus percentages. The headline metric.
• CONCENTRATION: top-hub edge-share + top:next ratio. High values = force-star.
• COMMUNITY: Louvain modularity. < 0.3 = no coherent clusters; > 0.75 = siloed islands.
• TOP HUBS / TOP BRIDGES: the high-influence notes. Useful for "what should I de-star?" or "what's a connector worth protecting?"

Install

Claude Code

pip install obsidian-graph-auditor
mkdir -p ~/.claude/skills
git clone https://github.com/build-with-dhiraj/obsidian-graph-auditor ~/.claude/skills/obsidian-graph-auditor

Then ask Claude Code: "audit my obsidian vault at ~/Documents/MyVault".

Cursor

pip install obsidian-graph-auditor
mkdir -p ~/.cursor/skills
git clone https://github.com/build-with-dhiraj/obsidian-graph-auditor ~/.cursor/skills/obsidian-graph-auditor

Gemini CLI

pip install obsidian-graph-auditor
mkdir -p ~/.gemini/skills
git clone https://github.com/build-with-dhiraj/obsidian-graph-auditor ~/.gemini/skills/obsidian-graph-auditor

Codex CLI

pip install obsidian-graph-auditor
mkdir -p ~/.codex/skills
git clone https://github.com/build-with-dhiraj/obsidian-graph-auditor ~/.codex/skills/obsidian-graph-auditor

What it does NOT do

• It does not modify your vault. Read-only by design.
• It does not call GPT, Claude, or any other LLM. Pure local Python.
• It does not rewrite your notes, change frontmatter, or move files.
• It does not require an Obsidian plugin install. Pure CLI.
• It does not require Obsidian to be installed at all. Works on any markdown directory with wikilinks.

Related

• Full rubric with citations: docs/RUBRIC.md
• Comparison vs Vault Inspector / Vault Physician / Vault Intelligence / obsidiantools / obsidian-graph-query: docs/COMPARISON.md
• Deep-dive on graph analysis and orphan remediation: docs/GRAPH-ANALYSIS.md