claude-receipts — 把 Claude Code 的花費印成一張收據

你不知道你每天在 AI 上花多少錢。

這句話聽起來很誇張，但仔細想一下：你每天開幾次 Claude Code session？每次對話大概用多少 token？Opus 和 Sonnet 的價差有多大？cache hit 率怎麼樣？如果你回答不出其中任何一個問題，你其實是矇著眼睛在燒錢。

不是因為你不在意花費。是因為花費對你來說是不可見的。

超商收據哲學

claude-receipts 做的事情很簡單：每次你結束一個 Claude Code session，它自動幫你印一張「收據」。

不是比喻。是真的收據——長得跟超商結帳的那張長長的紙一模一樣。上面列著你用了哪些模型、吃了多少 input / output / cache tokens、每個模型花了多少錢、session 總花費。你可以在瀏覽器看 HTML 版、在終端看 ASCII art 版，或者接上一台 Epson TM-T88V 熱感應印表機，真的把它印出來貼在牆上。

為什麼選收據這個形式？因為收據是人類已經建立了數十年的「消費認知介面」。你在超商看到收據上寫 $87，你立刻知道這代表什麼。但你看到「Opus: 42,831 input tokens, 12,456 output tokens」——什麼感覺？什麼感覺都沒有。數字太抽象了，大腦直接跳過。

把 token 數字轉換成錢，再把錢放進一個你大腦已經會自動處理的格式裡——這就是 claude-receipts 真正在做的事。不是技術創新，是介面創新。

一行指令，零設定

1	npx claude-receipts setup

做兩件事。在 ~/.claude/settings.json 加一個 SessionEnd hook，在 ~/.claude-receipts.config.json 建一個設定檔。裝完之後，每次 Claude Code session 結束——不管是 /exit、Ctrl+C、Ctrl+D 還是直接關視窗——hook 都會非同步觸發，收據就跳出來了。

要特別注意 Node.js 版本要 >= 22，ESM only。舊版 Node 會裝不起來。

背後的資料來源是 ccusage 這個 CLI 套件。claude-receipts 不自己算 token 和花費，而是呼叫 npx ccusage session --id <id> --json 拿精確數據。計算邏輯交給專門的工具，自己只負責呈現——這個分工很乾淨。如果你想移除，npx claude-receipts setup --uninstall 一行搞定。

印表機版本才是重點

HTML 和 ASCII art 都不錯，但真正讓這個工具從「有趣」變成「我要裝」的是印表機版。

接上一台二手的 ESC/POS 熱感應印表機（日拍上一兩千塊就有），每次 coding session 結束就嘟嘟嘟印一張出來。收據上還有 QR code 連回 GitHub repo。作者自己說：「It’s dumb, the receipts are beautiful, and I love it so much.」

# USB 連線
npx claude-receipts generate --output printer --printer usb

# 網路連線
npx claude-receipts generate --output printer --printer tcp --printer-host 192.168.1.100

# CUPS（macOS/Linux）
npx claude-receipts generate --output printer --printer cups --printer-name TM-T88V

有人覺得這是在搞笑。但想一下：你上次認真看自己 Claude Code 的花費是什麼時候？如果答案是「沒有」或「很久以前」，那問題不在於你不關心，而在於花費資訊的介面太差了。email 帳單你不會看，dashboard 你懶得開，但桌上一張實體收據？你不看也會看到。

這跟體重計放在浴室門口的道理一樣。不是要你每天焦慮自己多重，是讓數字自然進入視野，行為就會自己微調。

收據長什麼樣

一張收據從上到下：標頭有 Claude 的 ASCII logo 加你的地理位置和時間。Session 資訊包括專案名稱、session name、總時長。然後是重點——每個模型分別列出 input tokens、output tokens、cache read/write tokens，各自的小計。最後是總花費和 session ID。

cache read/write 的拆分是很實用的細節。你可以從收據上直接看出 prompt cache 的命中率——如果 cache read 占比很高，代表你的 session 有效利用了快取，省了不少錢。反過來，如果 cache write 很多但 cache read 很少，代表你的 context 一直在變，快取沒派上用場。

地理位置的偵測優先順序：CLI flag > config 設定 > IP geolocation（離線查詢）> fallback 顯示 “The Cloud”。可以用 npx claude-receipts config --set location="Taipei, Taiwan" 手動設定。

分享你的帳單

HTML 版收據有個「Share Publicly」按鈕，點下去會上傳到 Cloudflare Worker 產生一個公開連結。在 X 上分享你的 vibe coding 帳單目前蠻流行的——有人秀出一個 session 花了 $0.12，有人秀出花了 $15。數字本身不重要，重要的是它讓 AI 使用成本變成一個可以被討論的東西。

每 IP 每小時最多分享 10 次，算是合理的 rate limit。

收據也會自動存檔到 ~/.claude-receipts/projects/ 目錄，累積一陣子之後你可以回頭翻——哪個專案最燒錢、哪天用量最高、模型選擇有沒有隨時間改變。不用另外裝分析工具，收據本身就是資料。

背後的技術決策

整個工具的核心只有一個 SessionEnd hook。Claude Code 在 session 結束時把 session ID 和 transcript 路徑透過 stdin 傳進來，hook 接住之後做三件事：呼叫 ccusage 拿 token 數據、解析 transcript JSONL 拿 metadata、產生收據。

有幾個設計決策值得看。

第一，它透過檢查 stdin.isTTY 判斷是從 hook 觸發還是手動執行。Hook 觸發時 stdin 是 pipe，手動執行時是 TTY——用這個一行判斷就分開了兩種使用情境。

第二，ESC/POS 印表機指令是自己寫的 EscPosBuilder 類別，沒有用現成的 receipt printer 函式庫。對一個 442 stars 的小專案來說，自己寫印表機驅動聽起來有點瘋，但 ESC/POS 協定本身不複雜，自己寫反而比引入一個大依賴更乾淨。

第三，沒有測試。package.json 的 test script 只是 placeholder。這不是疏忽，是一種取捨——個人小專案追求的是「好玩且有用」，不是「可維護到三十年後」。