Theo dõi hạn mức Claude Code ngay trên thanh menu macOS với claude-quota

Theo dõi hạn mức Claude Code ngay trên thanh menu macOS với claude-quota

Một tiện ích nhỏ gọn nhưng hữu ích dành cho người dùng macOS giúp theo dõi hạn mức sử dụng Claude Code trực tiếp từ thanh menu. Công cụ hỗ trợ nhiều tài khoản, hiển thị cảnh báo màu sắc và đếm ngược thời gian reset, giúp lập trình viên quản lý tài nguyên AI hiệu quả hơn.

Giao diện thanh menu của claude-quota

Giới thiệu claude-quota

Claude Code đang trở thành công cụ hỗ trợ lập trình phổ biến, nhưng việc quản lý hạn mức sử dụng (quota) đôi khi gây khó khăn cho người dùng, đặc biệt khi làm việc với nhiều tài khoản khác nhau. claude-quota là một plugin SwiftBar dành cho macOS, giải quyết vấn đề này bằng cách hiển thị các thanh đo trực quan trên menu bar.

Mỗi thanh đo đại diện cho một tài khoản Claude Code, giúp bạn nắm bắt tình trạng sử dụng ngay lập tức mà không cần mở trình duyệt hay terminal.

Tính năng nổi bật

Công cụ này cung cấp cách trực quan hóa việc sử dụng API qua các chỉ thị màu sắc:

• Thanh màu xanh lá: Sử dụng bình thường dưới 70%.
• Thanh màu cam: Cảnh báo khi mức sử dụng đạt từ 70% trở lên.
• Thanh màu đỏ: Báo động mức độ cao khi đạt từ 90% trở lên.

Khi cửa sổ sử dụng 5 giờ bị lấp đầy, thanh đo sẽ chuyển sang chế độ đếm ngược thời gian reset (ví dụ: 4:28) thay vì hiển thị phần trăm. Đặc biệt, nếu chạm đến giới hạn hàng tuần (hard cap), thanh sẽ chuyển sang màu đen với đếm ngược đến khi reset tuần mới (ví dụ: 2D).

Menu thả xuống (dropdown) cung cấp chi tiết đầy đủ cho từng tài khoản, bao gồm:

• Cửa sổ sử dụng 5 giờ và hàng tuần.
• Giới hạn theo từng mô hình (nếu gói dịch vụ của bạn hỗ trợ).
• Các tín dụng sử dụng thêm (extra-usage credits).
• Thời gian reset.

Cách hoạt động và Bảo mật

Một trong những điểm mạnh của claude-quota là tính bảo mật và sự gọn nhẹ:

• Plugin đọc OAuth token của Claude Code từ macOS Keychain ở chế độ chỉ đọc (read-only). Nó không bao giờ làm mới hay ghi đè token, nên không thể đăng xuất bạn khỏi tài khoản.
• Công cụ truy vấn trực tiếp vào endpoint sử dụng nội bộ mà màn hình /usage của Claude Code sử dụng.
• Không yêu cầu mật khẩu, không thực hiện scraping (quét dữ liệu web) và không sử dụng dịch vụ bên thứ ba.

Lưu ý: Endpoint này là nội bộ của Claude Code và chưa được tài liệu hóa chính thức, nên các thay đổi trong tương lai từ Claude Code có thể yêu cầu một bản sửa nhỏ cho plugin này.

Cài đặt nhanh

Để cài đặt công cụ này, máy tính của bạn cần có macOS và Homebrew. Chạy lệnh sau trong terminal:

curl -fsSL https://raw.githubusercontent.com/grzegorz-raczek-unit8/claude-quota/main/install.sh | bash

Lần đầu tiên làm mới, macOS sẽ hiển thị hộp thoại yêu cầu quyền truy cập Keychain. Hãy chọn "Always Allow" (Luôn cho phép) để tiện ích hoạt động trơn tru.

Plugin sẽ tự động làm mới dữ liệu mỗi 5 phút (theo quy ước tên tệp của SwiftBar) và cung cấp tùy chọn "Refresh now" để làm mới thủ công.

Hỗ trợ nhiều tài khoản

Theo mặc định, plugin tự động phát hiện các tài khoản dựa trên các thư mục cấu hình ~/.claude hoặc ~/.claude-* có mục nhập Keychain tương ứng. Mỗi tài khoản sẽ được gắn nhãn theo hậu tố thư mục (ví dụ: ~/.claude-work sẽ hiển thị là W).

Nếu bạn muốn ghim hoặc đổi tên tài khoản (ví dụ khi sử dụng nhiều biến môi trường CLAUDE_CONFIG_DIR), hãy tạo tệp ~/.config/claude-quota/accounts với định dạng:

đường_dẫn_tài_khoản [tên_hiển_thị]

Ví dụ:

~/.claude-work Work
~/.claude-priv Priv

Để ẩn thanh đo của một tài khoản cụ thể trên menu bar (nhưng vẫn giữ chi tiết trong dropdown), bạn có thể chọn tùy chọn "Hide from menu bar" trong dropdown hoặc chỉnh sửa tệp ~/.config/claude-quota/hidden.

Gỡ cài đặt

Nếu bạn muốn gỡ bỏ công cụ, chỉ cần xóa tệp claude-quota.5m.py khỏi thư mục plugin SwiftBar (mặc định là ~/.swiftbar).