scan_date: 2026-07-29 mode: A（idea 先例掃描） tier: quick token_cost: ~9 萬 token（估）

Radar 報告：Claude Code session 成本監看 CLI

Idea 原文：一個 CLI 工具——從本地 log 聚合 token 用量，按專案／日期／模型分組，超過預算時發 Telegram 通知。

拆解：問題＝訂閱/用量不透明、超支無感｜對象＝Claude Code 重度個人用戶｜機制＝解析本地 JSONL → 聚合 → group by project/date/model → 門檻 → Telegram push｜差異點＝Telegram 告警＋預算門檻＋專案維度。

1. 裁決

四象限：一缸子（聚合層）＋ 零件散落沒人整合（告警層）——這題是兩層疊起來的，分開判才準：

層	象限	證據
聚合層（讀 JSONL、按專案/日期/模型分組）	一缸子	ccusage 17,542★／npm ~39 萬次/月；GitHub 單「claude code usage/cost/token tracker」三組詞就撈出 30+ 個活著的專案；AlternativeTo 另列 12 個
告警層（門檻 → Telegram 推播）	零件散落沒人整合	領導者明確拒收此範圍；全生態唯一做 Telegram 的是無授權的 GUI app；其餘 budget-guard 類全是 0-1★

建議路線：reference（不是 build，也不是 adopt/fork）

一句為什麼：你要的「聚合」已被 ccusage 用 --instances --project --json 完整解決，而你本機早就有一份可用的 costs.jsonl（602 列／49 sessions／13 個專案）和現成的 send_telegram 管線——這題真正缺的只有「門檻判斷＋推播」那 30-50 行膠水，不值得開一個新 CLI 專案。

⚠️ 同時要改題目：見 §4「死因分析」——在訂閱制下，用本地 log 算出來的美元「預算」不是會咬你的那條線。真正會咬的是伺服器端 5h／週滾動配額，而本地 log 看不到它。照原題做出來的東西，會在你最需要它的時候不響。

2. 硬閘門表（shortlist）

一票否決制：License（引用可否）／棄養／安全。

Repo	★	License	棄養檢查	安全	閘門
ccusage/ccusage	17,542	MIT（見註1）	pushed 2026-07-28（今日級）	無 OSSF 紀錄（見註2）	✅ 過
Maciek-roboblog/Claude-Code-Usage-Monitor	8,542	MIT	pushed 2026-07-05（3.5 週）	—	✅ 過
soulduse/ai-token-monitor	292	無 LICENSE 檔	pushed 2026-07-28（活躍）	—	❌ 擋（見註3）
ColeMurray/claude-code-otel	480	MIT	pushed 2025-06-17（13 個月）	—	❌ 擋（棄養）
boyand/cc-budget	29	MIT	pushed 2026-07-26（活躍）	—	✅ 過

註1（重要，差點誤判）：gh api repos/ccusage/ccusage 的 license.spdx_id 回 NOASSERTION，ecosyste.ms 也回 other——看起來像紅旗。實際拉 LICENSE 檔內容是標準 MIT License, Copyright (c) 2025 ryoppippi。是 GitHub 授權偵測器的假陽性，可安全引用。
註2：OSSF Scorecard 對 ccusage 回 404。已做負對照：同端點查 kubernetes/kubernetes 正常回 score 7.6 → 管道活著，是 ccusage 沒被收錄，小專案常態，非紅旗。
註3：repos/soulduse/ai-token-monitor/license 回 404，且 root 檔案清單（.gitignore, CLAUDE.md, README.md, index.html, package*.json, tsconfig*, vite.config.ts）確無 LICENSE。無授權＝著作權全保留＝不得抄碼、不得 fork 再發布。可以裝來用、可以看功能，但一行都不能借。這很可惜，因為它是全生態唯一把 Telegram 告警做完的。

3. 契合六維

維度	評	一句話
功能	⚠️	聚合需求 100% 已被 ccusage 覆蓋（`--instances` 按專案、`daily/weekly/monthly/session` 按日期、`--json` 可餵下游）；只有門檻＋推播沒人給
技術	⚠️	ccusage 已改寫成 Rust——想 fork 進去加告警，成本遠高於在外面包一層讀 `--json`
維運	✅	走 reference 路線幾乎零維運：一個 cron/Stop hook + 一支 shell script；資料源是你自己已在寫的 costs.jsonl，不依賴上游
團隊（AI agent 看得懂改得動）	✅	30-50 行 shell/python 膠水，subagent 一張工單就能寫完＋測；反之要 agent 去改 Rust 專案就重得多
生態	⚠️	ccusage bus factor＝1（ryoppippi 1,108 commits vs 次位人類 17）；Claude-Code-Usage-Monitor 同樣是 1（151 vs 9）。整個生態的頭部都靠單人維持——只依賴它的 JSON 輸出，不把邏輯綁進去是對的做法
退出成本	✅	膠水層可拋；若哪天 ccusage 死了，改讀自己的 costs.jsonl 即可（本來就有）

本機既有資產盤點（關鍵輸入）

這題你已經做完 70%：

資產	路徑	狀態
Stop hook 成本記錄器	`/Users/brianforest/Code/InfraSystem/hooks/cost-tracker.js`	✅ 已跑，含 RATE_TABLE
累積資料	`~/.claude/metrics/costs.jsonl`	✅ 602 列／49 sessions／2026-07-09～07-28
欄位	`timestamp, session_id, transcript_path, model, input_tokens, output_tokens, cache_write_tokens, cache_read_tokens, estimated_cost_usd`	✅ 模型維度、日期維度現成
專案維度	由 `transcript_path` 反推，實測可解出 13 個專案（InfraSystem 19／sys4Ethan 13／EverOS 5…）	✅ 現成，不需新欄位
查詢層	`skills/cost-tracking/SKILL.md`	✅ 已能做「今日 vs 昨日 vs 總計＋by model」
Telegram 推播	`bin/reboot-restore.sh` 的 `send_telegram`＋`~/Code/EverOS/notify/contibot.conf`	✅ 現成
缺口	門檻判斷＋觸發推播＋去重（別每輪都叫）	❌ 這就是全部要寫的東西

4. 差異化空間＋死因分析

還空著的縫

門檻→推播（真縫）。領導者親口關門：ccusage issue #259 "Real-Time Usage Alerts" 被 maintainer ryoppippi 以 "Closing during repository triage: this is not actionable or not planned for the current ccusage scope." 結案。不是沒人提，是刻意不做。
這個縫正在被商業化收割。ccusage README 置頂贊助欄現在掛著 Lineman.io — "unauthorized-spend alerts"（Team/Enterprise 付費方案）。OSS 側留白，付費側補位——這解釋了為什麼 OSS 一直沒人補。
CLI × 告警的交集是空的。AlternativeTo 12 個替代品裡 11 個是 macOS GUI／menu bar／notch app。唯一做 Telegram 的 ai-token-monitor 也是 GUI（且無授權）。headless／遠端／手機收通知這條路線，CLI 側沒人站。對你（Mini 常駐跑 session、人不在機器前）剛好是最痛的那格。

死因分析（為什麼一堆人試過都沒起來）

Show HN 墳場：HN Algolia 撈到成串發布紀錄，分數幾乎全在 1-4 分——Claud-ometer(1)、Agentic Metric(2)、Claude Ledger(1)、cc-usage-bar(1)、Claude Wrapped(1)、agentgraphed(4)。少數例外 CodeBurn(112)、ccusage 本體(75)。共同死因：同一份 JSONL 沒有第二種讀法——功能同質，先發者（ccusage）一旦補上 --instances/--json，後進者就沒有存在理由。
budget-guard 子類全軍覆沒：claude-code-budget-guard 有三個同名不同作者的 repo（kasimmj 1★、racoi12 0★、soksovanrith 0★），加上 claude-code-budget-gate 1★、credit-sentinel 0★、pirq 0★。這麼多人獨立想到同一個點子、全部 0-1★＝需求真實但產品化沒有價值（因為它本質是每個人自己 30 行的私人腳本，不是別人會安裝的東西）。這正是「reference 而非 build」的最強證據。
🚨 最關鍵的死因——量錯了東西：官方文件與 claude-code issue 都指向同一件事。
官方 Manage costs 明載：訂閱制下 /usage 的 session cost「isn't relevant for billing purposes」；且該頁數字「computed from local session history on this machine」，不含其他裝置與 claude.ai。
anthropics/claude-code #18550 留言（m13v）：「token-cost-per-command 和 server-enforced quota 是兩個不同的數字，混為一談就是大家會被突襲的原因。本地 log 工具（ccusage、Claude-Code-Usage-Monitor）統計的是 SDK 回報的量；Anthropic 在伺服器端執行 5h 滾動視窗＋週配額，SDK 看不到。」
對你的意義：你在 Max 訂閱上，estimated_cost_usd 是 API 等值估算（你自己的 cost-tracking skill 已寫明這點）。對「$X 美元預算」發告警，等於對一個不會扣你錢的數字設警報；而真正會讓你停工的 5h／週配額，本地 log 根本量不到。原題若照做，會做出一個「響的時候沒事、有事的時候不響」的東西。
修正建議：門檻改綁用量強度（每日 token 量、per-project 燃燒率、單 session 異常尖峰、模型配比），或直接把 /usage 的 plan bar 當真值來源；美元只當相對強度指標，別當閘門。

已排除的假設

~~「Claude Code 官方已內建這功能，所以不用做」~~ → 部分成立但不足以否決。官方確有 /usage（session 統計＋plan bar＋24h/7d 切換＋歸因到 skills/subagents/plugins/MCP），但查證後確認：官方沒有任何個人層級的門檻告警或外部推播；spend cap 只存在於 Teams/Enterprise 管理台與 Console workspace，個人 Pro/Max 沒有。官方唯一支援的即時外送路徑是 OpenTelemetry export（文件原文：「the only option that streams per-user token and cost metrics into your own observability stack in near real time」）。
~~「OTel 路線可以直接抄 claude-code-otel」~~ → 排除：該 repo 480★ 但 13 個月沒動（pushed 2025-06-17），單一貢獻者僅 4 個 commit——是個發布即停更的 demo，不是可依賴的基礎。OTel 路線本身仍有效，但要自己接。

5. 證據連結

主張	來源
ccusage 17,542★、Rust、MIT、單人 bus factor	`gh api repos/ccusage/ccusage` ＋ `/contributors`（實測 2026-07-29）
ccusage 真實採用 ~39 萬次/月且仍在成長	npm API：2026-01 143,602 → 05 329,575 → 06 411,334 → 07 375,239（至 07-28）
ccusage 已支援專案/日期/模型分組＋JSON	README：`ccusage claude daily --instances`、`--project myproject`、`--json`、`daily/weekly/monthly/session`
告警被 maintainer 判為 out of scope	https://github.com/ccusage/ccusage/issues/259 （2026-05-17 結案語）
告警需求持續存在（companion PWA）	https://github.com/ccusage/ccusage/issues/1445 ＋ https://github.com/arochab/claude-eats-tokens （1★，2026-06 建）
告警層被商業方案收割	ccusage README 贊助欄 Lineman.io「unauthorized-spend alerts」
唯一 Telegram 實作但無授權	https://github.com/soulduse/ai-token-monitor （README L14/L82/L148 明列 Discord/Slack/Telegram 門檻告警）＋ `/license` 404
官方無個人層級告警；OTel 是唯一即時外送	https://code.claude.com/docs/en/costs
本地 log ≠ 伺服器端配額	https://github.com/anthropics/claude-code/issues/18550 （m13v 留言）
Claude-Code-Usage-Monitor 採用量見頂回落	pypistats `claude-monitor`：2026-04 22,937 → 06 19,656 → 07 16,260
生態以 macOS GUI 為主	https://alternativeto.net/software/ccusage/ （12 個替代品中 11 個為 Mac GUI）
Show HN 同類多為低分	HN Algolia `ccusage`（917 hits）、`claude code usage cost`（109 hits）
本機資產現況	`~/.claude/metrics/costs.jsonl` 實測 602 列／49 sessions／13 專案

⚠️ 未採信的來源：WebSearch 摘要聲稱「ccusage 4.8k stars」與「/cost command」——經 gh api 與官方文件回源核實，兩者皆為過時資訊（實為 17,542★；文件現以 /usage 為主）。已排除不進報告結論。

6. 覆蓋聲明

已掃（12 管道）

管道	狀態	備註
`gh search repos`	✅	7 組詞；負對照 `ripgrep` 通過
`gh search issues`	✅	全域 3 發＋ccusage 內部 4 發
`gh api`（repo/contributors/issues/readme/license）	✅	8 個 repo
HN Algolia	✅	2 發；負對照 `ripgrep` 通過
AlternativeTo	✅	錨點 ccusage，取得 12 個替代品
WebSearch	✅	實發 6 發（上限 10）
npm downloads	✅	ccusage point＋2026 全年 range
pypistats	⚠️→✅	首發 HTTP 429；負對照 `requests` 正常 → 管道健康，重試後取得 claude-monitor 完整序列
OSSF Scorecard	⚠️	ccusage 404 無收錄；負對照 `kubernetes/kubernetes` 回 score 7.6 → 管道活著，非查無
deps.dev	✅	ccusage npm 版本序列正常
ecosyste.ms	✅	ccusage／ai-token-monitor
官方文件（WebFetch）	✅	code.claude.com/docs/en/costs 全文
本機資產盤點	✅	hooks／skills／costs.jsonl 實際讀取

未覆蓋

未掃	原因
中文詞矩陣（V2EX／知乎／掘金）	檔位沒開（deep 專用）
`gh search code` 實作層反查	檔位沒開（deep 專用，且 code search 額度 ~10/分需節流）
awesome 清單系統性掃描	檔位沒開
Wayback 死案考古	檔位沒開；本次死案以 HN 分數＋0-1★ 群體間接推定
學術/專利 pass	檔位沒開；本題屬工具層，預期收穫低
雪球外擴 ≤2 輪	檔位沒開
GitHub star 曲線	端點已死（時間線 API 404，見 channels.md）→ 人眼看 https://star-history.com/#ccusage/ccusage
Product Hunt	無公開 API；本次未耗 WebSearch 額度在此（判定邊際價值低於死因面）
Discord／X	無法自動化 → 見 §7

7. 手動後續（自動化不了，留給 Brian）

X 輿情（你有 Grok 訂閱）：搜 ccusage limits alert / claude code weekly limit surprise——本報告最大的不確定性是「大家實際上是被美元咬到還是被5h/週配額咬到」，X 上的即時抱怨最能定案。這直接決定你的門檻要綁哪個數字。
/usage 親眼看一次：跑 /usage 按 d／w 切 24h/7d，確認 plan bar 的實際呈現與「歸因到 skills/subagents/plugins/MCP」的粒度。若那個畫面已經夠用，膠水層可以只做「離開鍵盤時的推播」而不重做統計。
裝 ai-token-monitor 當競品體感（可裝不可抄——無授權）：它的 Telegram 門檻告警是全生態唯一完成品，值得看它「在哪個門檻、推什麼內容、如何避免洗版」，再用自己的實作重寫。
Discord 溫度：ccusage 若有社群頻道，可探「告警」相關討論是否被反覆提出——本報告只證明 issue 被關，沒證明社群壓力大小。

8. 附錄：全部查詢原文（含 0 結果）

GitHub — `gh search repos`

ripgrep（負對照）→ 3 筆 ✅ 管道活
claude code usage → 12 筆
claude code cost → 12 筆
ccusage → 12 筆
claude token tracker → 12 筆
claude code telegram → 10 筆（全為「用 Telegram 遙控 Claude Code」，非成本告警）
claude usage telegram → 2 筆，皆 0★（nianmunizeno92096-debug/claude-usage-telegram、voknil/claude-usage-telegram-bot）
claude code budget → 10 筆（budget-guard 群，最高 5★）
token budget alert → 2 筆，皆 0★ 且為 OpenClaw 自動生成

GitHub — `gh search issues`

ccusage budget alert → 0 結果
claude code cost notification → 1 筆（無關：agents-radar digest）
token usage budget limit notify → 0 結果
--repo ccusage/ccusage budget → 4 筆
--repo ccusage/ccusage notification → 9 筆
--repo ccusage/ccusage alert → 2 筆（#259／#1445，本報告核心證據）
--repo ccusage/ccusage "per project" → 2 筆（#1481：--project 在 weekly/monthly 缺席）

HN Algolia

ripgrep（負對照）→ 有 hits ✅ 管道活
ccusage → 917 hits
claude code usage cost → 109 hits

WebSearch（實發 6／上限 10）

site:reddit.com "claude code" cost tracking budget alert tool → 8 連結（site: 過濾未生效，回傳為泛生態文章；仍撈到 cc-budget／StackSpend／Bifrost）
"is there a tool that" claude code token usage budget notification alert → 7 連結（撈到 ai-token-monitor 的 Telegram 告警，關鍵命中）
claude code usage tracker telegram bot budget alert notification → 9 連結
"claude code" cost tracker abandoned OR "no longer maintained" OR deprecated OR "archived" usage monitor → 8 連結（撈到 anthropics/claude-code#18550；引擎明言未找到公認棄養的知名專案）
ccusage limitations per project grouping complaints reddit alternative → 0 相關結果（回傳全為 GitLab 議題，語意漂移）
claude code hook script send telegram notification when cost exceeds budget threshold → 9 連結（證明 CC→Telegram hook 是成熟通用模式：ccgram、claude-telegram-notifications、多篇教學）

直接 API／WebFetch

WebFetch https://code.claude.com/docs/en/costs → 全文 ✅
WebFetch https://alternativeto.net/software/ccusage/ → 12 個替代品 ✅
npm downloads point/range ccusage → ✅
pypistats claude-monitor overall → 首發 429 → 重試 ✅；負對照 requests ✅
scorecard ccusage → 404 無資料；負對照 kubernetes/kubernetes → 7.6 ✅
deps.dev npm/ccusage → ✅
ecosyste.ms ccusage／ai-token-monitor → ✅
gh api repos/{ccusage, Claude-Code-Usage-Monitor, claude-code-otel, ccseva, ai-token-monitor, cc-budget, claude-eats-tokens, claude-code-budget-guard} → ✅

檔位：quick（實發 WebSearch 6／10；未動 subagent fan-out）

升級 deep 可加掃的面： 1. 中文圈詞矩陣（V2EX／知乎／掘金）——中文開發者圈對訂閱配額的抱怨密度可能更高，且是本報告 §7 第 1 項不確定性的另一條解法。 2. gh search code 實作層反查——搜 costs.jsonl／estimated_cost_usd／~/.claude/projects 等實作詞彙，可撈出「沒取名字、藏在別人 dotfiles 裡」的私人腳本，這類最貼近你要做的形狀。 3. 雪球外擴 2 輪——從 ccusage 的 760 個 fork 與 dependents 往外挖，找有沒有人已經 fork 出告警分支。 4. Wayback 死案考古——把 0-1★ 的 budget-guard 群逐一驗屍，確認是「做完沒人用」還是「根本沒做完」；本報告目前是群體統計推定，非個案實證。 5. 下游 issue 反查——在整合 ccusage 的下游專案（ccseva、AgentLimits、viberank 等）搜 alert/notify，看告警需求在下游是否更旺。