neuro-vault-analytics

neuro-vault-analytics

Claude Code plugin and standalone CLI that turns Claudian conversation records into a weekly usage-review note for the neuro-vault project.

What it does

Use /analyze-vault-usage 7d from inside a Claude Code session, or run nv-analytics --period 7d directly. The CLI computes deterministic aggregates (top tools, N+1 patterns, dead ends, cache-hit ratios, subagent budgets) over your Claudian conversation records; the skill hands the aggregates to Claude for pattern critique, writes an actionable note to Inbox/neuro-vault-usage/YYYY-Www.md in the vault (canonical, indexed by Dataview), and a single-file HTML companion to /tmp/nv-analytics-<label>-<suffix>.html (ephemeral, with mass diagrams, side-by-side vault-vs-projects cards, and a tools-by-bucket table that read better than the equivalent Markdown tables).

By default the CLI scans every project under ~/.claude/projects/ for the period and slices the report into three parallel buckets:

• Vault — sessions started from inside the vault directory (full Claudian metadata).
• Projects — sessions from external repos that called the neuro-vault MCP (derived from SDK JSONL alone).
• Total — re-aggregation over the union.

A per-project breakdown lists each external project with at least one vault-touching session, plus its unique tools (tools used in that project and nowhere else). There is no --scope flag — the cross-project view is the default. See docs/superpowers/specs/2026-05-24-cross-project-breakdown-design.md for the design.

Install

From inside Claude Code, run two commands:

/plugin marketplace add AlexMost/neuro-vault-analytics
/plugin install neuro-vault-analytics@neuro-vault-analytics

The first registers this repo as a marketplace; the second installs the plugin from it. The skill /analyze-vault-usage and CLI nv-analytics ship together — nothing extra to copy.

For local development, point the marketplace at a cloned checkout:

/plugin marketplace add /path/to/neuro-vault-analytics
/plugin install neuro-vault-analytics@neuro-vault-analytics

Usage

From inside a Claude Code session in your vault:

/analyze-vault-usage 7d

Or directly from the shell:

nv-analytics --period 7d --vault ~/Obsidian --format json

The skill produces two artefacts per run:

• Inbox/neuro-vault-usage/<label>.md — the canonical review note, kept in the vault for diff and Dataview queries. Overwritten on rerun of the same period.
• /tmp/nv-analytics-<label>-<suffix>.html — a self-contained HTML report (Tailwind via CDN). The suffix is a 4-char base36 of Date.now(), so every run is a fresh file; macOS will reap /tmp for you. Open it in any browser; no server, no offline state.

The dual output is always produced — there is no --html flag. See docs/architecture/skill-protocol.md for the contract between the two prompts.

Running the CLI locally (without installing the plugin)

To inspect raw CLI output against a real vault — useful for debugging the analyzer or eyeballing aggregates before the LLM critique step:

git clone https://github.com/AlexMost/neuro-vault-analytics.git
cd neuro-vault-analytics
npm install
npm run build

# JSON (full report, machine-readable) — pipe through jq for readability
node dist/cli.js --vault ~/Obsidian --period 7d --format json | jq .

# Text (human-friendly summary)
node dist/cli.js --vault ~/Obsidian --period 7d --format text

You can also run from inside the vault directory and drop --vault (the CLI walks up looking for .obsidian/):

cd ~/Obsidian
node /path/to/neuro-vault-analytics/dist/cli.js --period 14d --format text

Available flags: --period <Nd|Nw> (e.g. 7d, 2w), --vault <path>, --sample-bytes <N|XKB|XMB> (default 50KB), --format json|text. There is also a --detail <sessionId> mode for dumping a single session's full SessionSummary (vault bucket only). If buckets.total.sessionsTotal is 0, either the period is empty or no session was vault-relevant — check warnings[] in the JSON output.

Sample output (truncated):