diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a58af0ad..a2c917c7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -2606,7 +2606,7 @@ }, { "name": "receipts", - "description": "Generate a personal Claude Code impact report from your local ~/.claude/projects transcripts, cross-referenced against your local git history — what you shipped, which projects it went to, and each project's share of your usage — for justifying usage to a manager or a self-review. Reads your session transcripts and runs read-only git commands in the projects they mention; mining is local and only a small aggregate summary (counts and project names) is sent to write the report, which is saved to your home directory and published nowhere.", + "description": "A personal Claude Code impact report for justifying your usage to a manager or a self-review: what you shipped, which projects it went to, and each project's share of your usage. Reads your ~/.claude/projects transcripts and runs read-only git locally; only counts and project names are sent to write it up, and the report stays on your machine.", "author": { "name": "Anthropic", "email": "support@anthropic.com" diff --git a/plugins/receipts/README.md b/plugins/receipts/README.md index 52330912..49a90325 100644 --- a/plugins/receipts/README.md +++ b/plugins/receipts/README.md @@ -4,6 +4,14 @@ Generate a personal Claude Code impact report — "receipts" — from your own session transcripts, for the conversation where someone asks what all this Claude Code usage is actually buying. +## Install + +``` +/plugin install receipts@claude-plugins-official +``` + +## Use + ``` /receipts # last 30 days (default) /receipts week # last 7 days @@ -12,115 +20,52 @@ Claude Code usage is actually buying. /receipts for myrepo # scope to one project ``` -You get two files in your home directory: a markdown report to paste into a -doc or a review, and a self-contained HTML receipt to open or attach. The -receipt has an **Export CSV** button for the by-project table, and prints to a -clean PDF. +Two files land in your home directory: a markdown report to paste into a doc or +a review, and a self-contained HTML receipt to open or attach. The receipt has +an **Export CSV** button and prints to a clean PDF. Nothing is published +anywhere. -## What it reports +Takes a few seconds — about 1s for a week, 5s for a year. + +## What you get - **What you shipped** — files and lines touched, commits carrying that work, PRs opened. - **By project** — sessions, active days, and each project's share of your - total compute. + usage. Work outside a repo is named for its directory; sessions that touched + no files at all (web searches, chat tools, dashboards) show as + *Research & investigation (no project)*, which for a lot of people is the + biggest row. - **Framing for a manager** — how to present the above without overclaiming. -## What counts - -The report's universe is **work you did with Claude Code**, mapped to the -project you did it on. Two consequences worth knowing before you read a number: - -**Claude Code's own machinery isn't your work.** The agent's scratchpad, its -per-session tool output, and `~/.claude` are excluded. On a real 30-day corpus -that removed 82% of the raw "lines touched" figure — files Claude wrote to talk -to itself, which no one shipped. - -**A project is where work landed, not where your shell was.** Sessions are -attributed to the projects their file operations touched (reads included — -reading a repo to answer a question is work in that repo), resolved to the git -root, or to the containing directory when it isn't a repo. Work outside a repo -still counts; it's named for its directory. Subagents share their parent's -session, so their work lands on the same project — there's no "delegated" -category, because delegation is a mechanism, not a kind of work. - -Sessions that touched no files and didn't run in a repo — web searches, Slack -reads, dashboard queries — land in **Research & investigation (no project)**. -That row is often the biggest one. It's real work that genuinely has no home on -disk, and naming it beats inventing a project for it. - -## Design notes - -**No dollar figures, anywhere.** A cost computed from local token counts is -inferred, not measured, and won't match your actual bill. Presenting one -invites the "that can't be right" reaction that discredits everything else in -the report. Spend appears only as relative percentages. - -**No invented "hours saved."** There's no baseline in local data to compute a -counterfactual from, and a fabricated multiplier undermines the real numbers -sitting next to it. The report deliberately leaves room for you to add -concrete wins by hand — those land better than any aggregate anyway. - -**No breakdown of spend by activity.** "38% of your compute went to reading -code" is the chart everyone wants and the data can't support. A turn's cost is -~90% context handling, half of it re-reading what earlier turns added, so -charging it to whichever tool fired that turn is a modeling choice rather than -a measurement — and the choice decides the answer. On one real month, three -equally defensible weightings put web search at 11%, 28% or 51%. Spend appears -once, per project, where it divides a real quantity by a real fact and the -ranking holds whichever weighting you pick. - -**Careful claims.** Commits are counted only when they were authored under the -identity git uses in that repo *and* their changed files include something -Claude Code touched. Both tests have to pass, which is what keeps a snapshot -cron out — it commits under your name but never touches the files Claude -edited — while still counting the commit you made by hand after Claude wrote -the code. The gap it leaves: a repo configured with a *shared* identity (a -release bot's, say) makes that bot "you" for that repo, so a bot commit -touching a file Claude also edited would count. Rare, and the alternative — -reading only your global identity — silently zeroes the commit count for -anyone using git's standard `includeIf` work/personal split, which is far more -common. - -Lines are "touched", not "written". Sessions, active days and commits are all -marked as columns that don't sum: a session spanning two projects is genuinely -in both, and worktrees of one repo share commits. +A few things the report deliberately won't tell you: no dollar figures, no +"hours saved", and no breakdown of spend by activity. Each of those would be a +guess dressed up as a measurement, and one bad number discredits the rest of +the page. What's left is meant to survive someone pushing back on it. ## Privacy -Mining is a local Node script — file I/O and `git`, no network calls. +Everything is read locally — file I/O and read-only `git`, no network calls. -It reads `~/.claude/projects/**/*.jsonl` — your own session history, already on -disk, all projects, for the window you ask for. To find out which of the -directories in there are repos, it runs `git rev-parse` in **every** directory -any session mentioned (on one real month, 152 of them), and in the ones that -are repos it also reads `user.email` and runs `git log`. All read-only, all -local. +It reads `~/.claude/projects/**/*.jsonl`, your own session history, already on +disk. To work out which of the directories mentioned there are git repos, it +runs `git rev-parse` in each of them, and in the ones that are, reads +`user.email` and runs `git log`. -The only thing that reaches the model is a small JSON summary: your name from -`git config user.name`, aggregate counts, and project names. Your email is read -but never emitted — it's used locally to match commit authorship. No code, no -conversation content, and no tool or MCP server names — the report has no -per-tool breakdown at all, so the list of services you've connected never -leaves the script. +The only thing that reaches the model is a small summary: your name from +`git config`, aggregate counts, and project names. No code, no conversation +content, and no tool or MCP server names — so the list of services you've +connected never leaves your machine. Your email is used locally to match commit +authorship and is never sent. -The report is written to your disk and published nowhere unless you explicitly -ask for a shareable version. Because repo names appear verbatim, the skill -lists them before you send the report anywhere. +Project names appear verbatim in the report, so the skill reads them back to +you before you send it anywhere. Use `/receipts for ` to scope it down. -## Relationship to `session-report` +## Which plugin do I want? -Both plugins read the same transcripts, and that's about where the similarity -ends. +[`session-report`](../session-report) reads the same transcripts to answer +*where am I wasting tokens* — cache hit rates, expensive prompts — and hands +you a list of optimizations. Install it to make your usage cheaper. -[`session-report`](../session-report) is a tuning tool. It asks *where am I -wasting tokens* — cache hit rates, disproportionate projects, expensive -prompts — and its output is a list of optimizations. The audience is you, and -the goal is to drive usage down. - -`receipts` is a justification tool. It asks *was this worth it* — what shipped, -in which repos, against what spend — and cross-references local git history to -tie usage to output. The audience is your manager, and the goal is to defend -the spend rather than trim it. - -Install `session-report` to make your usage cheaper. Install `receipts` to -explain why it was worth paying for. +`receipts` answers *was this worth it* — what shipped, in which projects, +against what spend. Install it to explain why the usage was worth paying for.