stats

mindgap stats

Reports per-turn wall-clock timing for Claude Code, aggregated across all sessions.

Definitions

• turn: one user prompt → final Stop. Starts at UserPromptSubmit, ends at Stop.
• turn duration: wall time of the whole turn — "how long the user waited".
• auto tool time: time inside PreToolUse → PostToolUse for Claude-driven tools (Bash, Read, Edit, Grep, Write, etc.). Real work.
• user-input tool time: same shape but for tools that block on the user — currently AskUserQuestion and ExitPlanMode. Not Claude's fault.
• Claude wait = turn duration − auto − user-input. Approximates LLM-side latency and harness overhead.

How to run

The stats script's absolute path is recorded by the logging hook on every fire. Read it and invoke:

node "$(cat ~/.claude/mindgap/stats-path)"

Variants:

Flag	Use when
--all	User wants full history, not last 20.
--since 24h / --since 30m / --since 7d	User asks about a recent window.
--session <id-prefix>	Drill into one session (8-char prefix shown in the table is enough).
--include-archive	Also include last week's archived log (mindgap.jsonl.prev).
--raw	Get structured JSON to do further math/plot in this turn.

If ~/.claude/mindgap/stats-path doesn't exist, the user hasn't sent any prompt since installing the plugin. Tell them to send any message first — the next hook fire will create the marker.

Presenting results

• The script prints a formatted table and aggregate. Echo it verbatim inside a fenced block; don't reformat into markdown tables — alignment will break.
• Add a 1–2 sentence read: which turns were outliers, whether wait or tool time dominated, anything that stands out.
• The current turn won't appear yet — its Stop hasn't fired. Mention this if the user expected to see it.

Don't

• Don't parse the JSONL yourself — use --raw if you need structured data.
• Don't equate "Claude wait" with pure model latency; it also includes harness overhead, hook execution, and any text Claude generated between tool calls. Call it "non-tool time" if precision matters.
• Don't lump AskUserQuestion time into "Claude's fault" — that's the user reading and clicking.

Weekly rotation

The log auto-rotates on ISO week boundaries (local time). The previous week sits in ~/.claude/mindgap.jsonl.prev until the next rotation overwrites it. If the user asks for data older than a week, run with --include-archive; data older than two weeks is gone.