Claude Session Usage Monitor

VS Code extension:在狀態列常駐顯示 Claude Code 的 context 使用率與帳號額度,並在 context 接近上限時提醒你判斷該用 /compact 還是 /clear。

顯示什麼

主畫面

狀態列(一直看得到):

5h 48% · Resets in 3 hr 36 min · ctx 16%

狀態列(tooltip):

• 5h — 帳號的 5 小時額度用量,來自 claude -p "/usage" 的官方數字
• Resets in … — 該額度還有多久重置。取不到重置時間時只省略這段,百分比照常顯示
• ctx — 目前聚焦的那個 Claude Code 對話頁籤的 context 使用率,切換頁籤就跟著換
• 任一數字達 80% 轉為警告色、90% 轉為錯誤色
• 滑鼠移上去顯示每週額度、兩個重置時間、目前對話的名稱與累計成本
• 點擊開啟儀表板

ctx 跟著哪個對話走

正常情況跟著目前聚焦的對話頁籤。有兩種情況會不是,而且 tooltip 一定會講明是哪一種:

第三種主要發生在同時開著多個還沒命名的新對話時——它們的頁籤標題全都是「Claude Code」,無從分辨。原因見下方「運作方式」。

儀表板(點狀態列或執行指令開啟):5 小時與每週額度、視窗內各 session 佔比、每個 session 的 token 拆解與成本、Skills/Tools 清單。目前聚焦的對話會置頂在額度摘要正下方並加上顏色標記。

額度剛重置、你還沒送出下一個請求的那段空檔裡,官方數字會給出百分比但沒有重置時間。這時百分比照常顯示,重置那一行改成「尚未開始新的 5 小時視窗」;要是連百分比都沒有,百分比顯示 —、視窗成本明細一併歸零,寫的是「目前沒有進行中的 5 小時視窗」。這兩句都不等於「無法取得官方用量資料」——那句才代表查詢本身失敗。任何一次額度更新都會把這一區整個重寫,不會留下上一個視窗的數字:右上角的「更新於」時間只要收到資料就會前進,靠它分辨不出旁邊的數字是新是舊。

通知:任一執行中 session 的 context 跨過 80% 時跳出 VS Code 通知,附「開啟儀表板」按鈕。文案會同時列出 /compact 與 /clear 及各自的適用時機——續做用前者、換任務用後者——判斷交給你自己下。每個 session 只提醒一次。通知範圍是所有專案,不限目前視窗。

指令

更新時機

兩種資料來源的成本差三個數量級,所以用不同節奏:

• 本機 transcript(context、成本、session 清單)—— fs.watch 事件驅動,Claude 一寫入就更新,閒置時零成本
• 帳號額度(5 小時、每週)—— 每 2 分鐘查一次,因為每次都要啟動 claude 行程(約 1.4 秒)

運作方式

全部讀取本機檔案,不呼叫 Anthropic API、不需要 API key:

• 解析 ~/.claude/projects/**/*.jsonl(Claude Code 自己的對話記錄),唯讀,不寫入
• 讀 ~/.claude/sessions/<pid>.json 得知目前活著的對話行程(Claude Code 為每個行程寫一個)
• 成本以 src/config.js 的價格表逐則訊息計算,依該則訊息的 model 與 cache TTL 分別計價
• 額度數字來自 claude -p "/usage" --no-session-persistence,那是 Claude Code 官方支援的指令。--no-session-persistence 不可省略,否則每次查詢都會在 ~/.claude/projects/ 留下一個 session 檔

顯示的金額標示為 notional(理論等值 API 成本),不是實際帳單——Pro 方案是固定月費。

session 保留多久

儀表板顯示目前這個 5 小時額度視窗內跑過的所有 session,額度重置時自然清空。超過 10 分鐘沒說話的標為「已結束」但仍留在畫面上——它花掉的額度還算在這個視窗裡。

另外,目前以頁籤開著的對話一律會列出來,即使它的用量屬於更早的視窗。這類卡片標為「本視窗未使用」、以虛線邊框與淡化區隔,且視窗成本與佔比一律為 0,不會影響上方的額度分配。沒有這條規則的話,額度剛重置後畫面會近乎全空,即使你開著四個對話。

判斷依據是最後一則對話訊息的時間,不是檔案修改時間:Claude Code 會把 mode、last-prompt、ai-title 這類簿記紀錄寫回舊的 transcript,光是開一次 session 選單就會把檔案時間頂上來,用它判斷會讓幾小時前的對話冒出來裝成剛活躍過。

頁籤怎麼對應到 session

VS Code 的頁籤物件只帶 viewType,沒有 session id,所以只能靠頁籤標題比對。實測確認頁籤標題是該 session 的最新 ai-title,有三種形態:完全相符、過長被截斷成 …、尚未命名時一律顯示「Claude Code」。比對順序是完全相符 → 前綴相符 → 無標題集合,而且只有命中唯一候選才採用。

這依賴 Claude Code 的內部行為,不是公開契約,對方改版可能失效——失效時會退回「本專案最近活動的對話」,不會壞掉。

已知限制

• VS Code 最小化或失焦時會漏接通知(狀態列顏色不會消失,回到編輯器仍看得到)
• 額度數字包含你其他裝置與 claude.ai 的用量,但視窗內各 session 佔比只看得到這台機器
• 同時開著兩個以上還沒命名的新對話時,無法分辨聚焦的是哪一個,會退回最近活動的那個
• 卡片上的 Context % 只算壓縮後留著的內容;Input/Output/Cache 與累計成本則涵蓋整段 session(含壓縮掉的歷史),兩者基準不同是刻意的
• 價格表需手動維護,更新時間註記在 src/config.js