Vault Stats

Vault Stats — Health Diagnostics & Usage Analytics

Shows vault-wide health metrics and current project usage analytics, then saves the report as a vault note for trend tracking.

Tools needed: Bash, Write

Procedure

Follow these steps exactly. Do not skip steps or reorder them.

Step 1 — Load config, derive project, compute stats

Run a single call that loads config, derives the project name, and computes all stats:

cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
python3 -c '
import sys, os, json
import glob; sys.path.insert(0, max(glob.glob(os.path.expanduser("~/.claude/plugins/cache/*/obsidian-brain/*/hooks")), default="hooks"))
from obsidian_utils import load_config
from vault_index import ensure_index
from vault_stats import compute_stats
c = load_config()
if not c.get("vault_path"):
    print("ERROR=vault_path not configured. Run /obsidian-setup first.")
    sys.exit(0)
vp = c["vault_path"]
folders = [c.get("sessions_folder", "claude-sessions"), c.get("insights_folder", "claude-insights")]
db = ensure_index(vp, folders)
project = os.path.basename(os.getcwd()).lower().replace(" ", "-")
result = compute_stats(db, project)
print("VAULT=" + vp)
print("INS=" + c.get("insights_folder", "claude-insights"))
print("PROJECT=" + project)
print("STATS_JSON=" + result)
'

Parse each output line as KEY=VALUE, splitting on the first =.

If an ERROR key is present, display its value and stop.

If STATS_JSON contains "error", display the error message and stop.

Parse STATS_JSON as JSON into a variable STATS.

Step 2 — Check for empty/missing data

If STATS.vault_wide.total_notes == 0:

> No notes indexed. Run /vault-reindex first.

Stop here.

If STATS.vault_wide.access_log_entries == 0, note this for later — display the stats tables normally but append a note at the end.

Step 3 — Format and display

Format the JSON into markdown tables and display to the user. Use this structure:

Vault-wide section:

## Vault Health

| Metric | Value |
|---|---|
| Total notes |  |
| DB size | = 1048576 → "X.X MB", >= 1024 → "X.X KB", else "N bytes"> |
| access_log entries |  |
| Oldest access |  |

## Signal Coverage

| Signal | Coverage | Notes |
|---|---|---|
| Activation (access history) | % (/) |  notes never accessed |
| Importance (non-default) | % (/) |  notes at default 5 |
| Both signals active | % (/) | Full 7-signal scoring |
| Neither signal | % (/) | Using 5-signal fallback |

## Access Patterns (last 30 days)

| Context | Count | % |
|---|---|---|
|  |

## Top 10 Most Accessed Notes

| # | Note | Accesses | Activation | Importance |
|---|---|---|---|---|
|  |

## Importance Distribution

| Score | Count |
|---|---|
| 1-3 (trivial) |  |
| 4-6 (standard) |  |
| 7-8 (significant) |  |
| 9-10 (critical) |  |

Project section:

---

## Project: 

| Metric | Value |
|---|---|
| Notes |  |
| Access events |  |
| Avg accesses/note |  |
| Notes with activation |  (%) |
| Notes with importance != 5 |  (%) |

## Recent Activity (last 7 days)

| Context | Count |
|---|---|
|  |

## Top 5 Most Accessed (this project)

| # | Note | Accesses | Activation | Importance |
|---|---|---|---|---|
|  |

Compute percentages: round(count / denominator * 100) — show as integer with %. For any percentage, if the denominator is 0, show 0%. This applies to all tables (signal coverage uses total_notes, access patterns uses sum of counts).

Format large numbers with commas (e.g. 1,832).

If access_log_entries == 0, append after the tables:

> Access tracking is active. Run /vault-search and /recall to start building history.

Snapshots section

If the JSON payload has a vault_wide.snapshots object with total_snapshots > 0, render a ## Snapshots section after the Importance Distribution table:

## Snapshots
Total: {total_snapshots} (compact: {by_trigger.compact}, clear: {by_trigger.clear}, auto: {by_trigger.auto})
Sessions with snapshots: {sessions_with_snapshots} (max {max_snapshots_per_session} per session)
Summarization: {summarized_fraction formatted as integer %}
Integrity: {orphaned_snapshots} orphan(s), {broken_backlinks} broken backlink(s)

If read_errors > 0, append on a new line before the auto-fix suggestion:

⚠ {read_errors} snapshot file(s) unreadable — check stderr for paths.

If orphaned_snapshots > 0 or broken_backlinks > 0, append on a new line:

Run `/vault-doctor` to auto-fix.

If total_snapshots == 0, omit the section entirely.

Step 4 — Save vault note

Generate filename:

1. Date: today's date YYYY-MM-DD
2. Hash: 4-character hex from date +%s | md5 | cut -c29-32 (macOS) or date +%s | md5sum | cut -c1-4 (Linux). Do NOT use tail -c 4.
3. Filename: YYYY-MM-DD-vault-stats-.md

Compose the full note: frontmatter + the markdown output from Step 3.

Frontmatter:

---
type: claude-stats
date: YYYY-MM-DD
project: 
tags:
  - claude/stats
  - claude/project/
---

Use the Write tool to save to $VAULT_PATH/$INSIGHTS_FOLDER/YYYY-MM-DD-vault-stats-.md.

Then set permissions:

chmod 600 "$VAULT_PATH/$INSIGHTS_FOLDER/YYYY-MM-DD-vault-stats-.md"

Step 5 — Confirm

Print:

> Stats saved to ``. View in Obsidian to track trends over time.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhattacherjee
• Source: abhattacherjee/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.