Skip to content

Hchen1218/token-receipt

BranchesTags

Repository files navigation

English | 简体中文

token-receipt

Turn AI token usage into a receipt with a punchline.

ASCII-native pricing-aware software-aware Claude Code Codex Trae Kimi Code OpenCode

No dashboard. No spreadsheet. No spiritual coping mechanism.
Just a bill that shows up before your denial does.

Why this exists

Most token tools explain usage.

token-receipt itemizes the damage.

It turns invisible AI spend into a thermal-paper artifact you can paste into chat, screenshot instantly, and post with a straight face.

Three rules run the whole project:

  • Visual first The output should look like checkout, not admin UI.
  • Data honest Real local logs first. Official pricing second. Unknowns stay unknown.
  • Artifact over analytics If it is not screenshot-worthy, it is not finished.

Preview

                    ▐▛███▜▌
                   ▝▜█████▛▘
                     ▘▘ ▝▝
                  CLAUDE CODE

        THANK YOU FOR CODING WITH Claude
      RECEIPT #: CC_20260427_151928_7CE382
           DATE: 2026-04-27 15:19:28
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PROVIDER                               ANTHROPIC
MODEL                          claude-sonnet-4.5
CONTEXT USED                              12,487
────────────────────────────────────────────────
ITEM                                      TOKENS
────────────────────────────────────────────────
Input Tokens                              12,487
Output Tokens                              3,215
Cache Read Tokens                          8,742
Reasoning Tokens                             128
Cache Write Tokens                         1,024
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOTAL                              15,702 TOKENS
────────────────────────────────────────────────
USD ESTIMATE                           $0.062851
PRICE                          claude-sonnet-4.5
PRICE DATE                            2026-04-25
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    THE LOGO LOOKS CALM. THE BILL DOES NOT.

        ||| ||||| || ||| | | || |||  | |
           CC_20260427_151928_7CE382

How to trigger it

There are three ways to use token-receipt.

1. Trigger it inside chat

If you installed this repo as a skill, the normal path is not “open terminal and figure it out.”

The normal path is: say what you want in the chat box of the software you are already using.

Strong trigger phrases:

  • token receipt
  • token bill
  • usage receipt
  • token 小票
  • 对话发票
  • AI 用量账单
  • 把这次对话打成小票
  • 看看这轮 token 消耗
  • 查看本次对话 Token 消耗

You can also be explicit about language:

  • token receipt in English
  • 中文版 token 小票

2. Let Claude Code do it automatically

Claude Code can auto-print a receipt on SessionEnd.

Install the hook:

python3 scripts/install_claude_auto_trigger.py

After that, ending a Claude Code session will auto-fire the receipt without an extra chat message.

3. Run the CLI directly

If you are not invoking it through a skill system, run the script yourself:

python3 scripts/token_receipt.py --agent-tool codex
python3 scripts/token_receipt.py --agent-tool claude-code
python3 scripts/token_receipt.py --agent-tool kimi-code
python3 scripts/token_receipt.py --agent-tool opencode
python3 scripts/token_receipt.py --agent-tool claude-code --language zh-CN
python3 scripts/token_receipt.py --session ~/.local/share/opencode/opencode.db --opencode-session-id ses_xxx --agent-tool opencode

Trigger matrix:

Software Manual trigger in chat Auto trigger
Codex Say token receipt or equivalent Not shipped
Claude Code Say token receipt or equivalent SessionEnd hook after install
Trae Say token receipt or equivalent Not shipped
Kimi Code Say token receipt or equivalent; CLI --agent-tool kimi-code Not shipped
OpenCode Say token receipt or equivalent; CLI --agent-tool opencode Not shipped

The footer is the feature

The footer is not decoration. It is the coup de grace.

This project is built around the idea that the last line on the receipt should feel like the model watched you spend context on one more revision and decided to leave a note.

Examples:

  • THE LOGO LOOKS CALM. THE BILL DOES NOT.
  • REASONING WAS BILLED SEPARATELY.
  • THE LAST REVISION WAS NOT THE LAST.
  • 画面稳了，预算死了。
  • 最后一版这个词，本来就不诚实。

If the receipt looks good but the footer has no sting, the job is not done.

Software support

It bills the software you are actually using. It does not quietly switch to another app's newer logs.

Software Status Data source Notes
Codex supported now Codex JSONL sessions Reads local session logs directly
Claude Code supported now Claude usage-data + projects Uses usage logs for tokens and transcripts for model lookup
Trae manual mode now Trae app storage Auto transcript import is not shipped yet
Kimi Code supported now kimi-cli context.jsonl (~/.kimi/sessions/ or KIMI_SHARE_DIR) Reads cumulative _usage.token_count; USD estimate omitted (no API split); use manual flags if you need priced input/output
OpenCode supported now opencode*.db SQLite under ~/.local/share/opencode/ (see OPENCODE_DATA_DIR, XDG_DATA_HOME) Reads session/message rows (message.data JSON: tokens, modelID); supports --scope latest-turn | session

Notes:

  • Some Trae builds use Trae CN / .trae-cn instead of Trae.
  • Inside Codex, the runtime can be detected and token-receipt reads Codex logs.
  • Inside Claude Code's SessionEnd hook, token-receipt reads Claude Code usage logs.
  • If you run the script from a plain shell and more than one local software log exists, pass --agent-tool explicitly. Cross-software guessing is intentionally disabled.
  • In current releases, --agent-tool trae is honest: it tells you to use manual mode instead of pretending Trae has clean JSONL session logs.

Model coverage

There are two layers of support:

  1. Receipt rendering Any model name can be rendered in manual mode.
  2. Price estimation Cost only shows up when the model exists in references/pricing.json.

Current mapped model families include:

  • OpenAI GPT-5 family, Codex family, GPT-4.1, GPT-4o, o3, o4-mini
  • Anthropic Claude Opus, Sonnet, and Haiku families
  • Google Gemini 2.x and 3.x families
  • Moonshot Kimi K2 family
  • DeepSeek DeepSeek V4 family
  • Alibaba Qwen family
  • Zhipu GLM family
  • Xiaomi MiMo family
  • MiniMax M2 family

If your model is not mapped yet, the receipt still renders. The price just refuses to roleplay.

What it actually reads

Current receipts intentionally stay conservative about what they print:

  • Input Tokens
  • Output Tokens
  • Cache Read Tokens
  • TOTAL
  • Reasoning Tokens when actually available
  • Cache Write Tokens when actually available

That policy is deliberate.

Better to omit a field than lie with confidence.

Quick start

No package manager is required right now. It runs on Python's standard library.

python3 scripts/token_receipt.py

If you run that inside Codex or Claude Code, the current software can be detected automatically. If you run it from a plain shell with multiple local software logs present, add --agent-tool.

Useful software-specific examples:

python3 scripts/token_receipt.py --agent-tool codex
python3 scripts/token_receipt.py --agent-tool claude-code
python3 scripts/token_receipt.py --agent-tool codex --scope session
python3 scripts/token_receipt.py --agent-tool claude-code --show-fields
python3 scripts/token_receipt.py --agent-tool trae --provider openai --model gpt-5.4 --input-tokens 12487 --output-tokens 3215

Useful rendering variants:

python3 scripts/token_receipt.py --width 48 --stream
python3 scripts/token_receipt.py --agent-tool codex --language en
python3 scripts/token_receipt.py --agent-tool claude-code --language zh-CN
python3 scripts/token_receipt.py --agent-tool claude-code --output html --write ./receipt.html
python3 scripts/token_receipt.py --agent-tool claude-code --session ~/.claude/usage-data/session-meta/${CLAUDE_SESSION_ID}.json --write /tmp/token-receipt.txt
python3 scripts/token_receipt.py --footer-tone snarky --conversation-summary "one more revision for visual polish"
python3 scripts/token_receipt.py --provider anthropic --agent-tool claude-code --model claude-sonnet-4.5 --input-tokens 12487 --cached-input-tokens 8742 --output-tokens 3215

Inside Claude Code skills, ${CLAUDE_SESSION_ID} resolves to the current Claude session.

What those flags mean in plain English:

  • --agent-tool codex Read Codex data and use the Codex receipt header.
  • --agent-tool claude-code Read Claude Code data and use the Claude Code receipt header.
  • --agent-tool trae Use Trae branding. For now, bring your own token counts.
  • --show-fields Ask the logs what they can actually prove.
  • --language en Print the English receipt.
  • --language zh-CN Print the Chinese receipt without forking the layout.
  • --output html Export a browser-printable receipt page instead of the monospace text artifact.
  • --write /tmp/token-receipt.txt Save the receipt quietly instead of dumping it into Bash stdout. This is the cleaner path inside Claude Code chat.
  • --write-html /tmp/token-receipt.html Keep the text receipt as the main artifact, but also save a printable HTML copy that can be linked back in hosts that support local file links.
  • --stream Print like a machine that knows you spent too much.

Printable HTML

The main artifact is still the monospace receipt inside chat.

HTML is the secondary route: useful when you want browser print preview, real printer output, or a cleaner handoff to thermal-printer workflows.

python3 scripts/token_receipt.py --agent-tool claude-code --output html --write ./receipt.html

Open receipt.html in a browser, hit Print receipt, and let the browser talk to the printer.

If your host can render local file links, the cleaner flow is dual export:

python3 scripts/token_receipt.py --agent-tool claude-code --write /tmp/token-receipt.txt --write-html /tmp/token-receipt.html

That keeps the monospace receipt in chat while also giving you a clickable printable HTML file.

The current HTML path is tuned for the same three things people actually notice:

  • a gray preview stage with a white receipt body, so the receipt edges stay visible on screen
  • a pure white print result, so the browser preview does not lie about the final paper
  • software-aware logos in HTML too: Claude Code uses a dedicated vector mark, while Codex and Trae use embedded image assets

Claude Code auto-trigger

Install:

python3 scripts/install_claude_auto_trigger.py

Uninstall:

python3 scripts/uninstall_claude_auto_trigger.py

This wires token-receipt into Claude Code's SessionEnd hook.

The conversation ends. The receipt arrives. The denial window closes.

Design philosophy

This project is intentionally opinionated.

  • No markdown tables as the primary artifact
  • No QR code for now
  • No made-up token fields just because another tool exposes them
  • No pretending platform-routed pricing is a direct vendor bill
  • No sanding away the weird, uncomfortable energy of a real receipt

If the output feels too clean, it probably stopped feeling true.

Validation

Before shipping changes, run:

python3 scripts/validate_receipt.py

It checks things like:

  • line width
  • required fields
  • logo alignment
  • barcode presence
  • pricing fallbacks
  • unsupported field leakage

Changelog

See CHANGELOG.md for the running update log.

Roadmap

  • Shipped now Printable HTML export for browser print preview and physical receipt workflows.
  • Next up Printer-first presets for common paper widths and cleaner print defaults.
  • Also planned Trae automatic session import once its local storage shape is stable enough to trust.

One-line thesis

Every prompt leaves a tab.

token-receipt just prints it before you can emotionally recover.

Inspired by chrishutchinson/claude-receipts.
Same receipt instinct. Different attitude. More software. Meaner footer.

About

Turn AI token usage into a receipt with a punchline.

Resources

Readme
Activity

Stars

51 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages