nerf-receipts — Claude Code plugin for session metrics
The nerf-receipts plugin tracks tool failures, repeated edits to the same file, and tokens per task. Use it to see whether those signals shift when the model changes.
MIT ★ 586 updated 2026-10-26
/plugin marketplace add karanb192/claude-code-hooks
/plugin install nerf-receipts@claude-code-hooksWhat nerf-receipts does
Hooks gather session-level counts in Claude Code: tool calls and failures, repeated edits to one file, and turn endings. When a session ends, the plugin reads token usage from its transcript and appends a record to a local JSONL ledger. Transcript text, tool inputs, and commands are not stored.
At the next session start, a trend card shows sparklines grouped by model ID and Claude Code version. It flags mean shifts of at least 25% that coincide with a model change; reporting starts after 6 sessions. You can also request the card with /nerf-receipts:receipts. The script makes no network calls, and the data stays on your machine. Transcript parsing has caps of 20000 lines and 16 MiB.
What it helps with
- track the share of failed tool calls
- spot repeated edits to the same file
- compare tokens per completed task across models
- check whether metric shifts coincide with a model change
Example prompts for the agent
- Show the model trends with
/nerf-receipts:receipts. - Compare tool-failure rates and tokens per task across model versions.
- Check whether the metrics shifted after the model changed.
How to install nerf-receipts
Plugin marketplace
/plugin marketplace add karanb192/claude-code-hooks/plugin install nerf-receipts@claude-code-hooksStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about nerf-receipts
How do I install nerf-receipts in Claude Code?
Run these commands in order: /plugin marketplace add karanb192/claude-code-hooks, then /plugin install nerf-receipts@claude-code-hooks. Restart Claude Code afterward.
What does nerf-receipts do?
It logs session metrics locally, including tool failures, repeated file edits, and tokens per task. A trend card charts the signals and flags changes that coincide with a model switch.
What data does nerf-receipts store?
The ledger contains counts and edited file paths. Tool inputs, commands, and transcript text are not retained, and the script makes no network requests.
Source text
nerf-receipts · MIT
# nerf-receipts > A personal flight recorder for Claude Code quality: records your own per-session failure rate, edit churn, and tokens/task by model version, and flags real shifts when a model changes. nerf-receipts registers on six hook events. As you work, `PostToolUse` and `PostToolUseFailure` count every tool call, its failures, and same-file edit churn; `Stop` and `SubagentStop` count turn-end events, all async, so they add no latency. At `SessionEnd` it parses token usage from the session transcript, finalizes four per-session signals (tool-failure rate, edit churn, turn-end count, tokens-per-completed-task), and appends one record to a JSONL ledger. At `SessionStart` it renders a trend card (a sparkline per metric, keyed by model id and Claude Code version) and flags meaningful shifts (>=25% relative change in the mean) that coincide with a model change. The same card is available on demand via `/nerf-receipts:receipts`. ## Install ``` /plugin marketplace add karanb192/claude-code-hooks # once per machine /plugin install nerf-receipts@claude-code-hooks ``` Restart Claude Code, done. (Or from a shell: `claude plugin install nerf-receipts@claude-code-hooks`.) ## What it does | Event | Runs | What happens | | ----- | ---- | ------------ | | `PostToolUse` | async (zero added latency) | Counts every tool call; records failures and same-file edit churn | | `PostToolUseFailure` | async (zero added latency) | Counts tool-call failures and edit churn | | `Stop` | async (zero added latency) | Counts turn-end events | | `SubagentStop` | async (zero added latency) | Counts subagent turn-end events | | `SessionEnd` | sync | Parses transcript tokens, finalizes the session, appends the record to the ledger | | `SessionStart` | sync | Renders the trend card and flags model-change shifts via `additionalContext` | `/nerf-receipts:receipts` renders the model-quality trend card on demand (failure rate, edit churn, tokens/task by model version, each with a sparkline). ## Configuration No environment variables. Tuning constants live at the top of `nerf-receipts.js`: - `MIN_SESSIONS_FOR_TREND` = 6: sessions required before a trend or shift is reported - `TREND_WINDOW` = 200: most recent sessions the trend card considers - `MAX_TRANSCRIPT_LINES` = 20000 and `MAX_TRANSCRIPT_BYTES` = 16 MiB: caps on transcript parsing State is stored as a JSONL ledger under `~/.claude/nerf-receipts/` (per-session in-flight logs under `~/.claude/nerf-receipts/sessions/`); event logs go to `~/.claude/hooks-logs/<date>.jsonl`. ## Data & privacy Only counts and edited file paths are recorded: tool inputs, commands, and transcript text are never persisted, so secrets in commands cannot land in the ledger. The script makes no network calls (it requires only `fs`, `path`, and `os`); everything stays on your local machine. ## Uninstall ``` /plugin uninstall nerf-receipts@claude-code-hooks ```
© Karan Bansal · MIT · karanb192/claude-code-hooks