經常寫 Claude Code 的開發者應該都有過這種經歷代碼正改到一半突然收到用量超限的提示只能停下來等窗口重置。網絡上有人把這個場景做成了一個很輕量的解決方案——一個體積很小、掛在菜單欄上的 Claude 用量小工具小到你不用打開任何面板掃一眼菜單欄就能決定“現在還能不能繼續跑”。這篇文章會沿著這個思路從零拆解這樣一款工具的設計與實現包含數據來源分析、代碼示例、開機自啟配置和排錯清單。1. 背景Claude Code 用量監控為什么是剛需1.1 Claude Code 是什么Claude Code 是 Anthropic 推出的終端 AI 編程代理工具。和網頁版 Claude 不同你可以在終端里通過命令行直接和它交互讓它讀取項目文件、分析報錯、生成代碼、執行測試甚至做多文件的重構。對很多把 Claude 當主力編程助手的開發者來說Claude Code 已經是日常開發流程的一部分。不過Claude Code 的底層依然要調用大模型接口也就意味著有“用量”這個概念。不同訂閱檔位、不同模型的調用都有額度限制一旦長時間高密度使用很可能觸發限流導致一段時間內無法繼續調用。1.2 用量的不確定性帶來的問題使用 Claude 或 Claude Code 時用量消耗并不總是線性的。你可能會遇到下面幾種情況一個包含大量上下文的重構任務可能一次對話就消耗大量 token。Claude Code 自動讀取項目文件后輸入 token 會快速增長。頻繁使用技能、多輪對話、長日志分析都會明顯拉高用量。代碼助手用起來太順手往往“一不小心”就連續跑了幾個小時。如果等到請求被拒絕時才意識到用量超了開發節奏已經被打斷了。此時還需要再切換工具、等窗口重置效率影響很大。1.3 菜單欄小工具的價值菜單欄小工具的核心價值是把“用量數據”從后臺搬到前臺。你不需要打開瀏覽器不需要敲一個命令也不需要切換到另一個窗口。只要眼睛掃一下屏幕右上角就能看到當前大概消耗了多少 token。設計這種工具的難點不是“顯示數據”而是“讓數據足夠直觀”這也是標題里提到的“small enough to read before you run it”——在你決定運行下一步操作之前就能判斷要不要繼續。與其等超限報錯不如提前從數據上預判。這也正是這類工具吸引人的地方把看不見的后臺消耗變成了菜單欄上一個可讀的指標。2. 整體設計思路2.1 工具要解決的核心問題我們要實現的是一個跑在 macOS 菜單欄上的小應用它需要滿足幾個關鍵要求常駐在菜單欄不占用 Dock 位置。能以極簡文字展示用量比如只顯示 token 總量的縮寫如“C 128K”。點擊菜單欄圖標后可以查看近期會話的詳細統計。支持定時刷新最好是可配置刷新間隔。足夠輕量不依賴較大的運行時。在動手前先要把數據來源想清楚。沒有穩定可靠的數據來源后面的展示再好看也沒有意義。2.2 數據來源選型Claude 的用量數據目前沒有一個完全統一的本地接口但從 Claude Code 的產品形態來看主要有三種思路方案說明優點局限解析本地會話日志Claude Code 會在本地目錄記錄會話 JSONL 文件里面包含每次調用的 usage 字段不依賴額外接口反映的是當前機器上的真實調用量只能統計當前機器上的會話跨設備數據無法覆蓋調用 Anthropic API 的模型用量信息API 響應中帶有 usage 字段可在自己寫的調用邏輯里累積數據精確適合自己開發應用時統計對 Claude Code 這類現成工具拿不到它的運行密鑰官方后臺或賬戶頁面手動查詢在賬戶設置中查看訂閱用量最接近官方真實額度無法自動化集成到菜單欄對菜單欄小工具來說最可行的方案是“解析本地會話日志”。這是最穩妥也最容易實現的方式不需要額外權限也不需要把 API Key 交給第三方小工具。2.3 技術選型macOS 菜單欄應用有幾種常見實現方式方案運行方式優點缺點Python rumpsPython 腳本啟動后創建一個菜單欄 App代碼短、開發快、容易改需要本機有 Python 環境Swift NSStatusItem編譯為原生 macOS 應用體積小、性能好、無外部依賴代碼量比 Python 多一些Electron Tray基于 Node.js / Web 技術前端能力強、跨平臺打包體積大、內存占用偏高Node.js menubar基于 Electron 的輕量封裝對有 JS 經驗的開發者友好同樣存在 Electron 體積問題如果你追求輕量和可維護性Python rumps 是最合適的。rumps 是一個專門用來開發 macOS 菜單欄應用的 Python 庫接口非常簡潔幾分鐘就能寫出來一個小工具。下面我以它為例展開完整實現。3. 環境準備與項目結構3.1 環境要求在開始寫代碼前先確認以下環境項目建議操作系統macOS 12 或更高版本Python3.9 或更高版本rumps0.4.0 或更高版本Claude Code已在本機安裝并使用過有會話日志生成版本需要根據你的項目實際情況調整本文示例以常見環境為例重點演示配置思路。如果你還沒有安裝過 Claude Code需要先安裝并完成一次登錄與對話這樣本地才會生成可分析的會話數據。3.2 安裝 rumps在終端中創建項目目錄并安裝依賴mkdir -p ~/claude-usage-menu cd ~/claude-usage-menu python3 -m venv venv source venv/bin/activate pip install rumps如果你希望全系統都能直接運行也可以使用pip install --user rumps。不過在 macOS 上更推薦用虛擬環境避免影響系統自帶的 Python 環境。3.3 項目結構建議按下面的方式組織文件claude-usage-menu/ ├── claude_usage_menu.py # 主腳本 ├── requirements.txt # 依賴清單 └── README.md # 使用說明其中requirements.txt內容很簡單rumps0.4.0這樣在換電腦或重新部署時只需要pip install -r requirements.txt就能恢復環境。4. 解析 Claude 用量數據4.1 理解 usage 數據格式要解析數據首先要知道數據長什么樣。Claude Code 的會話記錄以 JSONL 格式保存在本地默認目錄是~/.claude/projects/。目錄下的每個.jsonl文件對應一次項目會話文件名通常是項目路徑經過編碼后生成的字符串。這些 JSONL 文件中的每一行都是一個 JSON 對象記錄了會話過程中的一次事件。在 assistant 類型的事件里通常包含一個message字段而message.usage就是一次 API 調用的 token 消耗情況。典型的 usage 結構如下{ usage: { input_tokens: 1250, output_tokens: 418, cache_creation_input_tokens: 0, cache_read_input_tokens: 5120 } }各字段含義input_tokens本次請求的輸入 token 數。output_tokens本次響應的輸出 token 數。cache_creation_input_tokens寫入緩存的輸入 token 數。cache_read_input_tokens命中緩存后讀取的 token 數。其中緩存 token 在長上下文中很常見也是用量占比很高的一部分。如果只統計 input 和 output會明顯低估實際消耗。4.2 從會話日志中統計 token在寫代碼之前建議先手動確認一下日志路徑ls -lh ~/.claude/projects/ | head -20如果能看到一堆.jsonl文件說明日志路徑正確。接下來可以統計日志中的 usagegrep -o input_tokens:[0-9]* ~/.claude/projects/*.jsonl | awk -F: {s$2} END {print s}這個命令只是用來快速驗證數據是否存在。正式腳本建議使用 Python 來處理因為 JSONL 解析更健壯還能順便統計各類 token 的分布。4.3 獲取精確剩余額度的限制這里需要提醒你一下本地日志只能統計“當前這臺機器、當前登錄賬號在本地產生的會話消耗”。它不能直接拿到官方賬戶的精確剩余額度。不同訂閱檔位的額度策略由官方后臺控制可能會按時間段滾動重置也可能與套餐檔位有關。如果你需要精確的剩余額度數據最可靠的方式是登錄官方賬戶頁面查看。本地小工具更適合用來做“消耗趨勢提醒”而不是“精確額度儀表盤”。明白了這個邊界后我們的統計目標就是把本地會話日志中的 token 消耗讀出來按分類累加再展示到菜單欄。5. 實現菜單欄展示5.1 用 rumps 創建菜單欄應用rumps 的核心是App類和Timer類。我們先創建主腳本的骨架import json from pathlib import Path import rumps CLAUDE_DIR Path.home() / .claude / projects REFRESH_SECONDS 60這里的CLAUDE_DIR是日志目錄REFRESH_SECONDS是菜單欄的刷新間隔。建議不要設置太短比如 10 秒刷新一次因為每次刷新都要讀取并解析一批 JSONL 文件間隔太短會白白消耗 CPU。5.2 統計函數編寫一個函數用來掃描目錄下的所有.jsonl文件解析其中的 usage 字段并累加def collect_usage_stats(): stats { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0, message_count: 0, found: False, } if not CLAUDE_DIR.exists(): return stats for jsonl_file in CLAUDE_DIR.glob(*.jsonl): try: with open(jsonl_file, r, encodingutf-8) as fp: for line in fp: line line.strip() if not line: continue record json.loads(line) usage record.get(usage) if not usage: message record.get(message) if message: usage message.get(usage) if not usage: continue stats[found] True stats[input_tokens] int(usage.get(input_tokens, 0)) stats[output_tokens] int(usage.get(output_tokens, 0)) stats[cache_read_tokens] int(usage.get(cache_read_input_tokens, 0)) stats[cache_creation_tokens] int(usage.get(cache_creation_input_tokens, 0)) stats[message_count] 1 except (json.JSONDecodeError, OSError): continue return stats這段代碼做了幾件事先判斷日志目錄是否存在不存在就直接返回空統計。遍歷所有.jsonl文件。逐行解析 JSON同時兼容 usage 在頂層或嵌套在 message 里的兩種結構。分別累加輸入、輸出、緩存讀、緩存寫 token。用found標記本地是否真的有可用日志。如果某個文件損壞或包含非法 JSON腳本會跳過該文件不會因為單條壞數據導致整個程序崩潰。5.3 格式化顯示數字菜單欄空間有限直接顯示“123456789”這種長數字并不友好。我們需要一個格式化函數把大數字轉換為縮寫形式def format_tokens(count): if count 1_000_000: return f{count / 1_000_000:.1f}M if count 1_000: return f{count / 1_000:.0f}K return str(count)運行結果示例輸入 tokens1.2M 輸出 tokens850K 緩存讀取560K 緩存寫入128K這種縮寫形式正是“小到能看清”的關鍵在菜單欄上顯示C 2.1M比顯示完整數字更易讀。5.4 創建菜單欄應用接下來創建App子類把統計函數接入菜單欄class ClaudeUsageApp(rumps.App): def __init__(self): super().__init__(ClaudeUsage, titleC ...) self.menu [ rumps.MenuItem(正在讀取用量請稍候...), None, rumps.MenuItem(立即刷新, callbackself.refresh), rumps.MenuItem(退出, callbackself.quit), ] self.refresh() self.timer rumps.Timer(self.refresh, REFRESH_SECONDS) self.timer.start() def refresh(self, _None): stats collect_usage_stats() total_tokens ( stats[input_tokens] stats[output_tokens] stats[cache_read_tokens] stats[cache_creation_tokens] ) self.title fC {format_tokens(total_tokens)} self.menu.clear() self.menu.add(rumps.MenuItem(f輸入 tokens{format_tokens(stats[input_tokens])})) self.menu.add(rumps.MenuItem(f輸出 tokens{format_tokens(stats[output_tokens])})) self.menu.add(rumps.MenuItem(f緩存讀取{format_tokens(stats[cache_read_tokens])})) self.menu.add(rumps.MenuItem(f緩存寫入{format_tokens(stats[cache_creation_tokens])})) self.menu.add(rumps.MenuItem(f消息條數{stats[message_count]})) self.menu.add(None) self.menu.add(rumps.MenuItem(立即刷新, callbackself.refresh)) self.menu.add(rumps.MenuItem(退出, callbackself.quit))這里需要注意幾點self.title是菜單欄上顯示的標題我把它設置成類似C 1.8M的短文本。self.menu.clear()會清空舊菜單避免重復添加菜單項。rumps.MenuItem的callback參數指定點擊該菜單項時觸發的函數。rumps.Timer(self.refresh, REFRESH_SECONDS)會每隔 60 秒調用一次refresh。None在菜單列表中表示分隔線。最后添加啟動入口if __name__ __main__: ClaudeUsageApp().run()到這里一個最基本的 Claude 用量菜單欄工具就完成了。5.5 運行與驗證在項目目錄下運行python claude_usage_menu.py正常情況下菜單欄右上角會立刻出現一個C 0或C 0.9M類似的文字。點擊它會展開一個菜單展示各類 token 的統計信息。如果你在菜單欄中看不到任何內容可以查看終端輸出。rumps 在創建菜單欄應用時如果權限不足或運行環境異常通常會打印對應的錯誤信息。6. 完整代碼整合6.1 完整腳本把上面的代碼整合到一個文件里完整版如下# 文件路徑claude-usage-menu/claude_usage_menu.py import json from pathlib import Path import rumps CLAUDE_DIR Path.home() / .claude / projects REFRESH_SECONDS 60 def collect_usage_stats(): stats { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0, message_count: 0, found: False, } if not CLAUDE_DIR.exists(): return stats for jsonl_file in CLAUDE_DIR.glob(*.jsonl): try: with open(jsonl_file, r, encodingutf-8) as fp: for line in fp: line line.strip() if not line: continue record json.loads(line) usage record.get(usage) if not usage: message record.get(message) if message: usage message.get(usage) if not usage: continue stats[found] True stats[input_tokens] int(usage.get(input_tokens, 0)) stats[output_tokens] int(usage.get(output_tokens, 0)) stats[cache_read_tokens] int(usage.get(cache_read_input_tokens, 0)) stats[cache_creation_tokens] int(usage.get(cache_creation_input_tokens, 0)) stats[message_count] 1 except (json.JSONDecodeError, OSError): continue return stats def format_tokens(count): if count 1_000_000: return f{count / 1_000_000:.1f}M if count 1_000: return f{count / 1_000:.0f}K return str(count) class ClaudeUsageApp(rumps.App): def __init__(self): super().__init__(ClaudeUsage, titleC ...) self.menu [ rumps.MenuItem(正在讀取用量請稍候...), None, rumps.MenuItem(立即刷新, callbackself.refresh), rumps.MenuItem(退出, callbackself.quit), ] self.refresh() self.timer rumps.Timer(self.refresh, REFRESH_SECONDS) self.timer.start() def refresh(self, _None): stats collect_usage_stats() total_tokens ( stats[input_tokens] stats[output_tokens] stats[cache_read_tokens] stats[cache_creation_tokens] ) self.title fC {format_tokens(total_tokens)} self.menu.clear() self.menu.add(rumps.MenuItem(f輸入 tokens{format_tokens(stats[input_tokens])})) self.menu.add(rumps.MenuItem(f輸出 tokens{format_tokens(stats[output_tokens])})) self.menu.add(rumps.MenuItem(f緩存讀取{format_tokens(stats[cache_read_tokens])})) self.menu.add(rumps.MenuItem(f緩存寫入{format_tokens(stats[cache_creation_tokens])})) self.menu.add(rumps.MenuItem(f消息條數{stats[message_count]})) self.menu.add(None) self.menu.add(rumps.MenuItem(立即刷新, callbackself.refresh)) self.menu.add(rumps.MenuItem(退出, callbackself.quit)) if __name__ __main__: ClaudeUsageApp().run()這段代碼的核心邏輯并不復雜但已經覆蓋了從數據采集到菜單欄展示的完整鏈路。如果你使用的是較新版本的 rumps部分內部 API 可能會略有調整建議以官方文檔中的類方法為準。6.2 配置為開機啟動如果希望菜單欄工具在系統啟動后自動運行可以把腳本配置為一個 LaunchAgent。在~/Library/LaunchAgents/下創建一個 plist 文件?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.example.claudeusage/string keyProgramArguments/key array string/Users/yourname/claude-usage-menu/venv/bin/python/string string/Users/yourname/claude-usage-menu/claude_usage_menu.py/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ /dict /plist注意把/Users/yourname/替換成你的真實用戶路徑。使用虛擬環境中的 Python 可以避免依賴系統 Python 的包環境。然后執行加載命令launchctl load ~/Library/LaunchAgents/com.example.claudeusage.plist在新版 macOS 中系統可能會提示load已廢棄推薦使用launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.claudeusage.plist兩種命令都可以讓 LaunchAgent 生效你可以根據自己系統的提示選擇合適的方式。6.3 結果說明運行腳本并讓 Claude Code 繼續正常工作一段時間后你會看到菜單欄數字會隨著會話量上升而變化。舉例說明我的展示方式如果菜單欄顯示C 0說明本地沒有找到可用的 usage 日志或者所有日志中的 usage 字段都為空。如果菜單欄顯示C 1.2M說明本地累計消耗約 120 萬 token。點擊菜單欄后可以看到輸入、輸出、緩存讀取、緩存寫入四項的詳細拆分。這個數字只是一個相對參考目的是讓你形成“用量直覺”。當數字快速上漲時你至少會意識到當前會話消耗明顯偏大。7. 常見問題與排查7.1 菜單欄不顯示內容問題現象常見原因解決思路菜單欄沒有任何圖標或文字Python 環境缺少 rumpspip install rumps后重新運行終端直接退出腳本語法錯誤檢查 Python 版本和代碼縮進消息顯示權限失敗macOS 輔助功能或通知權限未授予在系統設置中檢查終端/腳本的權限如果菜單欄上沒有出現內容先確認終端里是否打印了異常堆棧。最常見的異常是ModuleNotFoundError: No module named rumps說明當前 Python 環境沒有安裝 rumps。記得先激活虛擬環境再運行腳本。7.2 讀取不到會話日志問題現象常見原因解決思路顯示 C 0本地沒有~/.claude/projects目錄先正常使用一次 Claude Code顯示 C 0日志路徑發生改變在終端執行ls -lh ~/.claude/projects/確認顯示 C 0日志文件為空新開一個會話再觀察解決這個問題的第一步是先確認日志目錄是否存在。如果 Claude Code 版本更新后路徑有變化需要同步調整CLAUDE_DIR常量。7.3 usage 統計為 0問題現象常見原因解決思路統計結果始終為 0JSONL 中的字段結構不兼容手動查看一行日志確認 usage 位置統計結果始終為 0日志文件編碼異常使用 Python 腳本逐行調試統計結果偏小只統計了輸入輸出沒有統計緩存確認解析邏輯包含 cache 字段可以手動查看一條日志來判斷結構head -5 ~/.claude/projects/*.jsonl如果日志中的 usage 字段嵌套層級和示例不同需要調整collect_usage_stats中的取值邏輯。7.4 請求被限流與 529 問題使用 Claude Code 時如果用量達到限制終端里可能會返回類似529或配額相關提示。這類錯誤通常不是本地文件導致的而是賬戶配額或服務端限流導致。如果菜單欄顯示用量并不高但 Claude Code 依然報錯說明本機日志只反映了部分會話或配額策略涉及跨設備賬戶維度。此時應優先查看官方賬戶頁面的用量說明而不是繼續依賴本地統計。8. 最佳實踐與工程建議8.1 數據統計單位與顯示策略菜單欄空間很有限不要堆砌完整數字。建議遵循以下原則只顯示一個總覽值例如C 1.8M。把詳細分類放到下拉菜單中。設置合理的刷新間隔建議 30 到 120 秒。在版本更新時留意 Claude Code 是否會改變日志路徑或字段結構。小工具的核心是“一眼可知”不是“信息大全”。把最關鍵的判斷依據放到最顯眼的位置其余細節收起來。8.2 隱私與安全Claude 會話日志中通常包含項目路徑、代碼上下文、文件內容等信息屬于敏感數據。在設計工具時要注意幾點不要在工具中上傳會話日志到任何第三方服務。不要圖方便把日志文件提交到公開倉庫。本地處理即可避免引入不必要的網絡請求。如果需要多人使用或發布到 GitHub建議把日志目錄路徑做成配置項避免硬編碼個人目錄。不要為了追求“好看”而把整個會話內容展示在菜單欄里這既沒有必要也容易造成信息泄露。8.3 從腳本到正式應用的演進建議如果只是自己使用上面的腳本已經足夠。但如果你希望把它打磨成一個更完善的小工具可以考慮以下方向方向說明圖標化在菜單欄中顯示一個小圖標用量接近閾值時圖標變色閾值提醒用量超過一定數值時彈出系統通知跨設備統計通過自建的日志同步服務匯總多臺設備的用量配置化把日志目錄、刷新間隔、顯示格式放到配置文件中原生 Swift 重寫去掉 Python 依賴打包成獨立 app其中“閾值提醒”是最值得優先實現的功能當本地累計 token 超過你設定的警戒線時用rumps.notification彈一個提示這樣你不需要一直盯著菜單欄也能在關鍵時刻收到提醒。9. 結語與可繼續優化的方向本文從 Claude Code 的用量管理痛點出發帶大家完整實現了一個菜單欄用量小工具。核心知識點可以歸納為幾條Claude Code 的會話數據會以 JSONL 形式留在本地usage 字段包含輸入、輸出和緩存三類 tokenPython 的 rumps 庫可以快速創建菜單欄應用LaunchAgent 可以讓腳本開機自啟。如果你正在高頻使用 Claude Code建議先把這個小工具跑起來觀察一兩天的數據變化你會對自己的真實消耗速度有一個更具體的感知。在此基礎上再決定是否需要做閾值提醒、跨設備統計或原生應用封裝。下一步值得探索的方向是了解 Claude 官方接口中的 usage 字段在不同模型下的差異以及如何在更長的時間維度上做用量趨勢可視化。把“能看到今天的用量”升級為“能預測未來幾小時會不會超限”才是這類小工具真正的進階價值。 Claude Code用量監控：打造macOS菜單欄Token小工具
經常寫 Claude Code 的開發者應該都有過這種經歷代碼正改到一半突然收到用量超限的提示只能停下來等窗口重置。網絡上有人把這個場景做成了一個很輕量的解決方案——一個體積很小、掛在菜單欄上的 Claude 用量小工具小到你不用打開任何面板掃一眼菜單欄就能決定“現在還能不能繼續跑”。這篇文章會沿著這個思路從零拆解這樣一款工具的設計與實現包含數據來源分析、代碼示例、開機自啟配置和排錯清單。1. 背景Claude Code 用量監控為什么是剛需1.1 Claude Code 是什么Claude Code 是 Anthropic 推出的終端 AI 編程代理工具。和網頁版 Claude 不同你可以在終端里通過命令行直接和它交互讓它讀取項目文件、分析報錯、生成代碼、執行測試甚至做多文件的重構。對很多把 Claude 當主力編程助手的開發者來說Claude Code 已經是日常開發流程的一部分。不過Claude Code 的底層依然要調用大模型接口也就意味著有“用量”這個概念。不同訂閱檔位、不同模型的調用都有額度限制一旦長時間高密度使用很可能觸發限流導致一段時間內無法繼續調用。1.2 用量的不確定性帶來的問題使用 Claude 或 Claude Code 時用量消耗并不總是線性的。你可能會遇到下面幾種情況一個包含大量上下文的重構任務可能一次對話就消耗大量 token。Claude Code 自動讀取項目文件后輸入 token 會快速增長。頻繁使用技能、多輪對話、長日志分析都會明顯拉高用量。代碼助手用起來太順手往往“一不小心”就連續跑了幾個小時。如果等到請求被拒絕時才意識到用量超了開發節奏已經被打斷了。此時還需要再切換工具、等窗口重置效率影響很大。1.3 菜單欄小工具的價值菜單欄小工具的核心價值是把“用量數據”從后臺搬到前臺。你不需要打開瀏覽器不需要敲一個命令也不需要切換到另一個窗口。只要眼睛掃一下屏幕右上角就能看到當前大概消耗了多少 token。設計這種工具的難點不是“顯示數據”而是“讓數據足夠直觀”這也是標題里提到的“small enough to read before you run it”——在你決定運行下一步操作之前就能判斷要不要繼續。與其等超限報錯不如提前從數據上預判。這也正是這類工具吸引人的地方把看不見的后臺消耗變成了菜單欄上一個可讀的指標。2. 整體設計思路2.1 工具要解決的核心問題我們要實現的是一個跑在 macOS 菜單欄上的小應用它需要滿足幾個關鍵要求常駐在菜單欄不占用 Dock 位置。能以極簡文字展示用量比如只顯示 token 總量的縮寫如“C 128K”。點擊菜單欄圖標后可以查看近期會話的詳細統計。支持定時刷新最好是可配置刷新間隔。足夠輕量不依賴較大的運行時。在動手前先要把數據來源想清楚。沒有穩定可靠的數據來源后面的展示再好看也沒有意義。2.2 數據來源選型Claude 的用量數據目前沒有一個完全統一的本地接口但從 Claude Code 的產品形態來看主要有三種思路方案說明優點局限解析本地會話日志Claude Code 會在本地目錄記錄會話 JSONL 文件里面包含每次調用的 usage 字段不依賴額外接口反映的是當前機器上的真實調用量只能統計當前機器上的會話跨設備數據無法覆蓋調用 Anthropic API 的模型用量信息API 響應中帶有 usage 字段可在自己寫的調用邏輯里累積數據精確適合自己開發應用時統計對 Claude Code 這類現成工具拿不到它的運行密鑰官方后臺或賬戶頁面手動查詢在賬戶設置中查看訂閱用量最接近官方真實額度無法自動化集成到菜單欄對菜單欄小工具來說最可行的方案是“解析本地會話日志”。這是最穩妥也最容易實現的方式不需要額外權限也不需要把 API Key 交給第三方小工具。2.3 技術選型macOS 菜單欄應用有幾種常見實現方式方案運行方式優點缺點Python rumpsPython 腳本啟動后創建一個菜單欄 App代碼短、開發快、容易改需要本機有 Python 環境Swift NSStatusItem編譯為原生 macOS 應用體積小、性能好、無外部依賴代碼量比 Python 多一些Electron Tray基于 Node.js / Web 技術前端能力強、跨平臺打包體積大、內存占用偏高Node.js menubar基于 Electron 的輕量封裝對有 JS 經驗的開發者友好同樣存在 Electron 體積問題如果你追求輕量和可維護性Python rumps 是最合適的。rumps 是一個專門用來開發 macOS 菜單欄應用的 Python 庫接口非常簡潔幾分鐘就能寫出來一個小工具。下面我以它為例展開完整實現。3. 環境準備與項目結構3.1 環境要求在開始寫代碼前先確認以下環境項目建議操作系統macOS 12 或更高版本Python3.9 或更高版本rumps0.4.0 或更高版本Claude Code已在本機安裝并使用過有會話日志生成版本需要根據你的項目實際情況調整本文示例以常見環境為例重點演示配置思路。如果你還沒有安裝過 Claude Code需要先安裝并完成一次登錄與對話這樣本地才會生成可分析的會話數據。3.2 安裝 rumps在終端中創建項目目錄并安裝依賴mkdir -p ~/claude-usage-menu cd ~/claude-usage-menu python3 -m venv venv source venv/bin/activate pip install rumps如果你希望全系統都能直接運行也可以使用pip install --user rumps。不過在 macOS 上更推薦用虛擬環境避免影響系統自帶的 Python 環境。3.3 項目結構建議按下面的方式組織文件claude-usage-menu/ ├── claude_usage_menu.py # 主腳本 ├── requirements.txt # 依賴清單 └── README.md # 使用說明其中requirements.txt內容很簡單rumps0.4.0這樣在換電腦或重新部署時只需要pip install -r requirements.txt就能恢復環境。4. 解析 Claude 用量數據4.1 理解 usage 數據格式要解析數據首先要知道數據長什么樣。Claude Code 的會話記錄以 JSONL 格式保存在本地默認目錄是~/.claude/projects/。目錄下的每個.jsonl文件對應一次項目會話文件名通常是項目路徑經過編碼后生成的字符串。這些 JSONL 文件中的每一行都是一個 JSON 對象記錄了會話過程中的一次事件。在 assistant 類型的事件里通常包含一個message字段而message.usage就是一次 API 調用的 token 消耗情況。典型的 usage 結構如下{ usage: { input_tokens: 1250, output_tokens: 418, cache_creation_input_tokens: 0, cache_read_input_tokens: 5120 } }各字段含義input_tokens本次請求的輸入 token 數。output_tokens本次響應的輸出 token 數。cache_creation_input_tokens寫入緩存的輸入 token 數。cache_read_input_tokens命中緩存后讀取的 token 數。其中緩存 token 在長上下文中很常見也是用量占比很高的一部分。如果只統計 input 和 output會明顯低估實際消耗。4.2 從會話日志中統計 token在寫代碼之前建議先手動確認一下日志路徑ls -lh ~/.claude/projects/ | head -20如果能看到一堆.jsonl文件說明日志路徑正確。接下來可以統計日志中的 usagegrep -o input_tokens:[0-9]* ~/.claude/projects/*.jsonl | awk -F: {s$2} END {print s}這個命令只是用來快速驗證數據是否存在。正式腳本建議使用 Python 來處理因為 JSONL 解析更健壯還能順便統計各類 token 的分布。4.3 獲取精確剩余額度的限制這里需要提醒你一下本地日志只能統計“當前這臺機器、當前登錄賬號在本地產生的會話消耗”。它不能直接拿到官方賬戶的精確剩余額度。不同訂閱檔位的額度策略由官方后臺控制可能會按時間段滾動重置也可能與套餐檔位有關。如果你需要精確的剩余額度數據最可靠的方式是登錄官方賬戶頁面查看。本地小工具更適合用來做“消耗趨勢提醒”而不是“精確額度儀表盤”。明白了這個邊界后我們的統計目標就是把本地會話日志中的 token 消耗讀出來按分類累加再展示到菜單欄。5. 實現菜單欄展示5.1 用 rumps 創建菜單欄應用rumps 的核心是App類和Timer類。我們先創建主腳本的骨架import json from pathlib import Path import rumps CLAUDE_DIR Path.home() / .claude / projects REFRESH_SECONDS 60這里的CLAUDE_DIR是日志目錄REFRESH_SECONDS是菜單欄的刷新間隔。建議不要設置太短比如 10 秒刷新一次因為每次刷新都要讀取并解析一批 JSONL 文件間隔太短會白白消耗 CPU。5.2 統計函數編寫一個函數用來掃描目錄下的所有.jsonl文件解析其中的 usage 字段并累加def collect_usage_stats(): stats { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0, message_count: 0, found: False, } if not CLAUDE_DIR.exists(): return stats for jsonl_file in CLAUDE_DIR.glob(*.jsonl): try: with open(jsonl_file, r, encodingutf-8) as fp: for line in fp: line line.strip() if not line: continue record json.loads(line) usage record.get(usage) if not usage: message record.get(message) if message: usage message.get(usage) if not usage: continue stats[found] True stats[input_tokens] int(usage.get(input_tokens, 0)) stats[output_tokens] int(usage.get(output_tokens, 0)) stats[cache_read_tokens] int(usage.get(cache_read_input_tokens, 0)) stats[cache_creation_tokens] int(usage.get(cache_creation_input_tokens, 0)) stats[message_count] 1 except (json.JSONDecodeError, OSError): continue return stats這段代碼做了幾件事先判斷日志目錄是否存在不存在就直接返回空統計。遍歷所有.jsonl文件。逐行解析 JSON同時兼容 usage 在頂層或嵌套在 message 里的兩種結構。分別累加輸入、輸出、緩存讀、緩存寫 token。用found標記本地是否真的有可用日志。如果某個文件損壞或包含非法 JSON腳本會跳過該文件不會因為單條壞數據導致整個程序崩潰。5.3 格式化顯示數字菜單欄空間有限直接顯示“123456789”這種長數字并不友好。我們需要一個格式化函數把大數字轉換為縮寫形式def format_tokens(count): if count 1_000_000: return f{count / 1_000_000:.1f}M if count 1_000: return f{count / 1_000:.0f}K return str(count)運行結果示例輸入 tokens1.2M 輸出 tokens850K 緩存讀取560K 緩存寫入128K這種縮寫形式正是“小到能看清”的關鍵在菜單欄上顯示C 2.1M比顯示完整數字更易讀。5.4 創建菜單欄應用接下來創建App子類把統計函數接入菜單欄class ClaudeUsageApp(rumps.App): def __init__(self): super().__init__(ClaudeUsage, titleC ...) self.menu [ rumps.MenuItem(正在讀取用量請稍候...), None, rumps.MenuItem(立即刷新, callbackself.refresh), rumps.MenuItem(退出, callbackself.quit), ] self.refresh() self.timer rumps.Timer(self.refresh, REFRESH_SECONDS) self.timer.start() def refresh(self, _None): stats collect_usage_stats() total_tokens ( stats[input_tokens] stats[output_tokens] stats[cache_read_tokens] stats[cache_creation_tokens] ) self.title fC {format_tokens(total_tokens)} self.menu.clear() self.menu.add(rumps.MenuItem(f輸入 tokens{format_tokens(stats[input_tokens])})) self.menu.add(rumps.MenuItem(f輸出 tokens{format_tokens(stats[output_tokens])})) self.menu.add(rumps.MenuItem(f緩存讀取{format_tokens(stats[cache_read_tokens])})) self.menu.add(rumps.MenuItem(f緩存寫入{format_tokens(stats[cache_creation_tokens])})) self.menu.add(rumps.MenuItem(f消息條數{stats[message_count]})) self.menu.add(None) self.menu.add(rumps.MenuItem(立即刷新, callbackself.refresh)) self.menu.add(rumps.MenuItem(退出, callbackself.quit))這里需要注意幾點self.title是菜單欄上顯示的標題我把它設置成類似C 1.8M的短文本。self.menu.clear()會清空舊菜單避免重復添加菜單項。rumps.MenuItem的callback參數指定點擊該菜單項時觸發的函數。rumps.Timer(self.refresh, REFRESH_SECONDS)會每隔 60 秒調用一次refresh。None在菜單列表中表示分隔線。最后添加啟動入口if __name__ __main__: ClaudeUsageApp().run()到這里一個最基本的 Claude 用量菜單欄工具就完成了。5.5 運行與驗證在項目目錄下運行python claude_usage_menu.py正常情況下菜單欄右上角會立刻出現一個C 0或C 0.9M類似的文字。點擊它會展開一個菜單展示各類 token 的統計信息。如果你在菜單欄中看不到任何內容可以查看終端輸出。rumps 在創建菜單欄應用時如果權限不足或運行環境異常通常會打印對應的錯誤信息。6. 完整代碼整合6.1 完整腳本把上面的代碼整合到一個文件里完整版如下# 文件路徑claude-usage-menu/claude_usage_menu.py import json from pathlib import Path import rumps CLAUDE_DIR Path.home() / .claude / projects REFRESH_SECONDS 60 def collect_usage_stats(): stats { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0, message_count: 0, found: False, } if not CLAUDE_DIR.exists(): return stats for jsonl_file in CLAUDE_DIR.glob(*.jsonl): try: with open(jsonl_file, r, encodingutf-8) as fp: for line in fp: line line.strip() if not line: continue record json.loads(line) usage record.get(usage) if not usage: message record.get(message) if message: usage message.get(usage) if not usage: continue stats[found] True stats[input_tokens] int(usage.get(input_tokens, 0)) stats[output_tokens] int(usage.get(output_tokens, 0)) stats[cache_read_tokens] int(usage.get(cache_read_input_tokens, 0)) stats[cache_creation_tokens] int(usage.get(cache_creation_input_tokens, 0)) stats[message_count] 1 except (json.JSONDecodeError, OSError): continue return stats def format_tokens(count): if count 1_000_000: return f{count / 1_000_000:.1f}M if count 1_000: return f{count / 1_000:.0f}K return str(count) class ClaudeUsageApp(rumps.App): def __init__(self): super().__init__(ClaudeUsage, titleC ...) self.menu [ rumps.MenuItem(正在讀取用量請稍候...), None, rumps.MenuItem(立即刷新, callbackself.refresh), rumps.MenuItem(退出, callbackself.quit), ] self.refresh() self.timer rumps.Timer(self.refresh, REFRESH_SECONDS) self.timer.start() def refresh(self, _None): stats collect_usage_stats() total_tokens ( stats[input_tokens] stats[output_tokens] stats[cache_read_tokens] stats[cache_creation_tokens] ) self.title fC {format_tokens(total_tokens)} self.menu.clear() self.menu.add(rumps.MenuItem(f輸入 tokens{format_tokens(stats[input_tokens])})) self.menu.add(rumps.MenuItem(f輸出 tokens{format_tokens(stats[output_tokens])})) self.menu.add(rumps.MenuItem(f緩存讀取{format_tokens(stats[cache_read_tokens])})) self.menu.add(rumps.MenuItem(f緩存寫入{format_tokens(stats[cache_creation_tokens])})) self.menu.add(rumps.MenuItem(f消息條數{stats[message_count]})) self.menu.add(None) self.menu.add(rumps.MenuItem(立即刷新, callbackself.refresh)) self.menu.add(rumps.MenuItem(退出, callbackself.quit)) if __name__ __main__: ClaudeUsageApp().run()這段代碼的核心邏輯并不復雜但已經覆蓋了從數據采集到菜單欄展示的完整鏈路。如果你使用的是較新版本的 rumps部分內部 API 可能會略有調整建議以官方文檔中的類方法為準。6.2 配置為開機啟動如果希望菜單欄工具在系統啟動后自動運行可以把腳本配置為一個 LaunchAgent。在~/Library/LaunchAgents/下創建一個 plist 文件?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.example.claudeusage/string keyProgramArguments/key array string/Users/yourname/claude-usage-menu/venv/bin/python/string string/Users/yourname/claude-usage-menu/claude_usage_menu.py/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ /dict /plist注意把/Users/yourname/替換成你的真實用戶路徑。使用虛擬環境中的 Python 可以避免依賴系統 Python 的包環境。然后執行加載命令launchctl load ~/Library/LaunchAgents/com.example.claudeusage.plist在新版 macOS 中系統可能會提示load已廢棄推薦使用launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.claudeusage.plist兩種命令都可以讓 LaunchAgent 生效你可以根據自己系統的提示選擇合適的方式。6.3 結果說明運行腳本并讓 Claude Code 繼續正常工作一段時間后你會看到菜單欄數字會隨著會話量上升而變化。舉例說明我的展示方式如果菜單欄顯示C 0說明本地沒有找到可用的 usage 日志或者所有日志中的 usage 字段都為空。如果菜單欄顯示C 1.2M說明本地累計消耗約 120 萬 token。點擊菜單欄后可以看到輸入、輸出、緩存讀取、緩存寫入四項的詳細拆分。這個數字只是一個相對參考目的是讓你形成“用量直覺”。當數字快速上漲時你至少會意識到當前會話消耗明顯偏大。7. 常見問題與排查7.1 菜單欄不顯示內容問題現象常見原因解決思路菜單欄沒有任何圖標或文字Python 環境缺少 rumpspip install rumps后重新運行終端直接退出腳本語法錯誤檢查 Python 版本和代碼縮進消息顯示權限失敗macOS 輔助功能或通知權限未授予在系統設置中檢查終端/腳本的權限如果菜單欄上沒有出現內容先確認終端里是否打印了異常堆棧。最常見的異常是ModuleNotFoundError: No module named rumps說明當前 Python 環境沒有安裝 rumps。記得先激活虛擬環境再運行腳本。7.2 讀取不到會話日志問題現象常見原因解決思路顯示 C 0本地沒有~/.claude/projects目錄先正常使用一次 Claude Code顯示 C 0日志路徑發生改變在終端執行ls -lh ~/.claude/projects/確認顯示 C 0日志文件為空新開一個會話再觀察解決這個問題的第一步是先確認日志目錄是否存在。如果 Claude Code 版本更新后路徑有變化需要同步調整CLAUDE_DIR常量。7.3 usage 統計為 0問題現象常見原因解決思路統計結果始終為 0JSONL 中的字段結構不兼容手動查看一行日志確認 usage 位置統計結果始終為 0日志文件編碼異常使用 Python 腳本逐行調試統計結果偏小只統計了輸入輸出沒有統計緩存確認解析邏輯包含 cache 字段可以手動查看一條日志來判斷結構head -5 ~/.claude/projects/*.jsonl如果日志中的 usage 字段嵌套層級和示例不同需要調整collect_usage_stats中的取值邏輯。7.4 請求被限流與 529 問題使用 Claude Code 時如果用量達到限制終端里可能會返回類似529或配額相關提示。這類錯誤通常不是本地文件導致的而是賬戶配額或服務端限流導致。如果菜單欄顯示用量并不高但 Claude Code 依然報錯說明本機日志只反映了部分會話或配額策略涉及跨設備賬戶維度。此時應優先查看官方賬戶頁面的用量說明而不是繼續依賴本地統計。8. 最佳實踐與工程建議8.1 數據統計單位與顯示策略菜單欄空間很有限不要堆砌完整數字。建議遵循以下原則只顯示一個總覽值例如C 1.8M。把詳細分類放到下拉菜單中。設置合理的刷新間隔建議 30 到 120 秒。在版本更新時留意 Claude Code 是否會改變日志路徑或字段結構。小工具的核心是“一眼可知”不是“信息大全”。把最關鍵的判斷依據放到最顯眼的位置其余細節收起來。8.2 隱私與安全Claude 會話日志中通常包含項目路徑、代碼上下文、文件內容等信息屬于敏感數據。在設計工具時要注意幾點不要在工具中上傳會話日志到任何第三方服務。不要圖方便把日志文件提交到公開倉庫。本地處理即可避免引入不必要的網絡請求。如果需要多人使用或發布到 GitHub建議把日志目錄路徑做成配置項避免硬編碼個人目錄。不要為了追求“好看”而把整個會話內容展示在菜單欄里這既沒有必要也容易造成信息泄露。8.3 從腳本到正式應用的演進建議如果只是自己使用上面的腳本已經足夠。但如果你希望把它打磨成一個更完善的小工具可以考慮以下方向方向說明圖標化在菜單欄中顯示一個小圖標用量接近閾值時圖標變色閾值提醒用量超過一定數值時彈出系統通知跨設備統計通過自建的日志同步服務匯總多臺設備的用量配置化把日志目錄、刷新間隔、顯示格式放到配置文件中原生 Swift 重寫去掉 Python 依賴打包成獨立 app其中“閾值提醒”是最值得優先實現的功能當本地累計 token 超過你設定的警戒線時用rumps.notification彈一個提示這樣你不需要一直盯著菜單欄也能在關鍵時刻收到提醒。9. 結語與可繼續優化的方向本文從 Claude Code 的用量管理痛點出發帶大家完整實現了一個菜單欄用量小工具。核心知識點可以歸納為幾條Claude Code 的會話數據會以 JSONL 形式留在本地usage 字段包含輸入、輸出和緩存三類 tokenPython 的 rumps 庫可以快速創建菜單欄應用LaunchAgent 可以讓腳本開機自啟。如果你正在高頻使用 Claude Code建議先把這個小工具跑起來觀察一兩天的數據變化你會對自己的真實消耗速度有一個更具體的感知。在此基礎上再決定是否需要做閾值提醒、跨設備統計或原生應用封裝。下一步值得探索的方向是了解 Claude 官方接口中的 usage 字段在不同模型下的差異以及如何在更長的時間維度上做用量趨勢可視化。把“能看到今天的用量”升級為“能預測未來幾小時會不會超限”才是這類小工具真正的進階價值。