claude-receipts: Printing a Thermal Receipt for Every Claude Code Session

What claude-receipts solves, and who it is actually for

Claude Code sessions end, and the cost of them is not something you see at the moment you close the terminal. claude-receipts takes the spend of a single session and renders it as a receipt: token counts broken down by model, input and output tokens, cache reads and writes, and a total cost. The README describes the author picking up a second hand receipt printer and hooking it to Claude Code's SessionEnd hook, with ccusage doing the cost arithmetic.

The audience is narrow on purpose. You need Claude Code installed, Node.js 22.0.0 or later, and an interest in the artifact itself. This is not a finance tool and not a team dashboard. The README calls the project "dumb" and the receipts "beautiful" in the same sentence, which is a fair summary of its ambitions. If you want a spreadsheet of monthly spend, this is the wrong shape of tool. If you want a physical slip of paper that says what one session cost, it is exactly the right one.

How the SessionEnd hook, ccusage and the transcript fit together

The mechanism has three moving parts, and the README lays them out in order. First, the SessionEnd hook. When you exit Claude Code, it calls npx claude-receipts generate --output html, passing the session ID over stdin. Second, data collection: the package shells out to ccusage session --id <session-id> to get the token and cost figures. Third, transcript parsing: it reads the session transcript JSONL to pull metadata such as the session name, timestamps and message count.

That division of labour matters. Cost numbers come from ccusage, not from the package's own reading of the transcript, and the README notes that for sessions which exist the package uses ccusage session --id to fetch accurate totals "rather than sub-session slices." The transcript supplies the descriptive fields. Receipt generation then renders the combined data, saves HTML to ~/.claude-receipts/projects/[session-name].html, optionally sends it to a printer, and in hook mode opens the HTML in your default browser.

Location detection is a small chain rather than a single source: the --location flag first, then the location setting in the config file, then offline IP geolocation through geoip-lite, and finally the string "The Cloud". That fallback is worth knowing about, because a receipt printed from a machine with no geolocation match will say The Cloud rather than a city.

Installing claude-receipts and generating a first receipt

The README gives a single setup command. It configures the SessionEnd hook in your global ~/.claude/settings.json and creates a config file at ~/.claude-receipts.config.json. Nothing is compiled by hand and no global install is required, since the package is invoked through npx.

npx claude-receipts setup

After that, exiting a Claude Code session generates a receipt and opens it in your browser. If you would rather not wait for a session to end, generate one for the most recent session manually.

npx claude-receipts generate

To see the receipt as ASCII art in the terminal instead of a browser tab, pass the console output format. The README lists html, console and printer as the accepted values, and multiple formats can be comma-separated.

npx claude-receipts generate --output console

For a specific session, use a session ID or a UUID prefix. The README's example uses a short prefix rather than a full UUID.

npx claude-receipts generate --session 9356d5e2

Configuration is managed through the config subcommand. The README shows setting location, timezone and printer, and a --show flag for reading the current values back.

npx claude-receipts config --set timezone="Asia/Kuala_Lumpur"
npx claude-receipts config --show

The default config file is minimal, containing only a version field, so location, timezone and printer are all optional additions.

Thermal printing: the Epson TM-T88V constraint and its escape hatch

Printing is the part of the project with the least generality. The README states that claude-receipts supports Epson TM-T88V thermal printers and compatible models, over USB via --printer usb or over the network via --printer tcp://192.168.1.100. There is a warning block in the README that says printing mileage may vary, that the author tested with an Epson TM-T88V on macOS, and that other models may have different capabilities or require code adjustments. Pull requests for printer compatibility are invited.

That is an honest constraint rather than a defect. ESC/POS is a family of dialects, and the README's troubleshooting section names the practical fallout: on Linux you may need permission to access USB devices under /dev/usb/lp*, and network printers should use port 9100, the default ESC/POS port. If your printer is not in the TM-T88V lineage, treat printing as something you will need to verify rather than assume. The HTML and console outputs carry no such hardware dependency, and the README's own roadmap lists HTML receipts with browser auto-open, console ASCII art mode and real thermal printing as completed items, with accurate session cost tracking listed last.

Where claude-receipts fails, and the case against using it

Two failure modes are documented, and both are worth reading before you commit to the hook. The first is "Cannot determine transcript path", which the README attributes to manually generating a receipt when the most recent session lacks a valid project path. The suggested fixes are to run from inside a SessionEnd hook or to work in a Claude Code session and let it auto-generate. In other words, manual generation is not always available on demand.

The second is more interesting. Very short sessions, such as a "hello world" prompt followed by an immediate exit, may not appear in ccusage yet. The README says the hook exits silently rather than printing a wrong receipt. Silent failure is the right call for correctness, but it means a missing receipt is not necessarily a bug: it can be a session that was too short to be recorded. If you use Claude Code in many tiny bursts, expect gaps.

There is also a structural limitation. The package depends on ccusage for cost data, so if ccusage cannot see your sessions, claude-receipts cannot either. The README's own diagnostic is to run npx ccusage session --json and confirm it returns something. That dependency is a single point of failure for the whole cost pipeline, and the package has no fallback path of its own for pricing.

How it differs from ccusage and from the Anthropic billing console

The closest alternative is ccusage itself, which claude-receipts already depends on. ccusage answers the question "what did I spend?" in the terminal or as JSON, and it is the source of truth for the numbers here. The difference is presentation and trigger. ccusage is a query you run; claude-receipts is an event that fires when a session ends, and it produces a formatted artifact, either an HTML page saved under ~/.claude-receipts/projects/ or a physical slip. If you only want totals, installing claude-receipts adds a layer you do not need, and the README's troubleshooting already points you at npx ccusage session --json as the underlying check.

The other reference point is Anthropic's own billing surfaces. Those are account-level and periodic: they tell you what a billing period cost. claude-receipts is session-level and immediate, with a per-model token breakdown attached to one conversation. The two answer different questions, and the receipt is not a substitute for an invoice. Anyone searching for a Claude subscription receipt or a PDF of payments is looking at account billing, not at this package, which produces receipts for Claude Code sessions and saves HTML rather than PDF.

Licence, maintenance and what upgrading costs you

The package is MIT licensed, and the repository is not archived. The last push was on 2026-05-09, which is more than four months before today, so the project is not something to describe as under active development. Releases are sparse: v1.0.0 on 2026-01-29 and v1.1.0 on 2026-02-05, with no release since. Treat it as a finished side project that receives occasional attention rather than a rapidly moving dependency.

For an MIT-licensed CLI that you invoke through npx, the upgrade cost is low but not zero. The package pins a set of runtime dependencies including ccusage, commander, chalk, date-fns, execa, fs-extra, geoip-lite, ora, prompts and usb. A major version bump in any of those is the kind of change that would land in a new release, and since releases are infrequent, you may sit on an older dependency tree for a while. The engines field requires Node.js 22.0.0 or later, so the runtime floor is the more immediate constraint. The repository's test script is a placeholder that exits with an error, which means there is no automated test suite to lean on when judging an upgrade; the practical check is to regenerate a receipt and compare it against a known session. Nothing here is legal advice, and the MIT terms are short enough to read directly in the LICENSE file.

Editorial conclusion

Adopt claude-receipts if you already run Claude Code, want a per-session cost artifact, and either have an Epson TM-T88V class printer or are content with HTML and console output. Skip it if you need a supported, cross-printer billing tool, or if your sessions are short enough that ccusage has not recorded them yet. Verify two things first: that npx ccusage session --json returns data on your machine, and that Node.js is at 22.0.0 or later. The thermal path is the part with real caveats, so test it on your own hardware before wiring it into a SessionEnd hook.

Frequently asked questions

Official sources

1. chrishutchinson/claude-receipts on GitHub
2. License: MIT
3. Project website
4. README
5. Releases