Theo dõi usage limit Claude trên desktop bằng một script

Bạn đang để Claude Code chạy một refactor dài thì màn hình báo "You've reached your usage limit". Con số đó vẫn nằm sẵn ở Settings → Usage trên claude.ai, nhưng không ai nhớ mở trang đó trước khi quá muộn. Có một cách rẻ hơn: kéo nó ra desktop, và hiểu vì sao nó tụt nhanh dần về cuối phiên.

Widget một file cho Windows và macOS

Dự án mã nguồn mở claude-usage-widgets đóng gói ba hạn mức của trang Usage thành một widget thường trú: Current session (5h) — cửa sổ trượt 5 tiếng, Week, all models — trần tuần, và Week, Opus / Sonnet — trần tuần theo từng model, khi gói của bạn có. Mỗi hạn mức có thanh tiến trình và đồng hồ đếm ngược tới lúc reset; màu chuyển xanh dưới 70%, hổ phách tới 90%, đỏ trên mức đó.

Bản Windows là một file .ps1 duy nhất dựng UI WPF — tác giả chọn PowerShell 5.1 vì máy Windows 10/11 nào cũng có sẵn, không cần cài .NET SDK, Node hay Python. Bản macOS là plugin SwiftBar viết bằng JXA (JavaScript for Automation), vốn ship kèm mọi máy Mac; chu kỳ refresh nằm ngay trong tên file, claude-usage.5m.js nghĩa là chạy mỗi 5 phút.

Số liệu lấy từ đâu — và rủi ro đi kèm

Không có public API cho usage. Widget gọi đúng endpoint mà web app claude.ai dùng, xác thực bằng cookie sessionKey của trình duyệt: GET /api/organizations để tìm org UUID, rồi GET /api/organizations/{org_uuid}/usage. Response trả về mỗi hạn mức một entry gồm utilization và resets_at — chỉ cần một phần trăm và một timestamp. Nếu bạn dùng Claude Code và chưa lưu session key, cả hai widget fallback sang OAuth token trong ~/.claude/.credentials.json rồi gọi api.anthropic.com/api/oauth/usage, trả về cùng cấu trúc.

Tác giả nói rõ: đây là internal endpoint không có tài liệu, có thể đổi bất cứ lúc nào, và dự án không liên kết với Anthropic. Thêm một điểm cần cân nhắc trước khi dán key: session key là quyền truy cập đầy đủ vào tài khoản claude.ai của bạn. Widget mã hoá nó bằng DPAPI trên Windows và Keychain trên macOS, nhưng script ngắn — đọc trước khi chạy. Khi widget báo 401/403 nghĩa là key hết hạn, thường do bạn vừa logout claude.ai.

Vì sao hạn mức tụt nhanh dần về cuối phiên

Một bài đo khác giải thích phần còn lại. Mỗi request gửi lại toàn bộ hội thoại, nên phiên càng dài thì mỗi lượt càng nặng. Tác giả đo một phiên Opus 5.5 của chính mình: 236 request, 88.434.005 input token, quý đầu trung bình 152.605 token/request (10,2% phiên), quý cuối 593.768 token/request (39,6%) — tức mỗi request cuối phiên cõng khoảng 3,9 lần token của request đầu phiên.

Prompt caching không xoá được đường cong đó, nó chỉ hạ đơn giá. Cache read trên Opus 5.5 và Sonnet 5.5 tính 0,05x giá input gốc; cache write thì đắt hơn hẳn. Trên gói subscription, Claude Code yêu cầu cache một tiếng cho hội thoại chính và ghi cache tốn 2x giá input; dùng API key hoặc usage credit thì cache mặc định 5 phút, ghi tốn 1,25x. Chênh lệch 2x so với 0,05x là tỉ lệ 40 ăn 1 — nên mỗi lần bạn rời máy đủ lâu để cache hết hạn, request kế tiếp phải ghi lại toàn bộ context đã tích luỹ. Trong log của tác giả, một lần quay lại sau 108 phút phải ghi lại 177.133 token.

Làm gì tiếp

Kiểm tra bạn đang nằm ở TTL nào trước: chạy claude -p "hello" --output-format json rồi xem usage.cache_creation — ephemeral_1h_input_tokens là cache một tiếng, ephemeral_5m_input_tokens là năm phút. Hai con số ở trên gợi ý hướng tối ưu rõ ràng, dù đây là phân tích chứ không phải khuyến nghị từ nguồn: cắt phiên theo đơn vị công việc thay vì để mở cả ngày, và canh các quãng nghỉ dài rơi vào lúc context còn nhỏ. Có widget trên thanh menu, bạn thấy được cả hai điều đó trước khi chạm trần, chứ không phải sau.