为什么值得关注

它逆向分析了 Claude Code CLI 的 OAuth 端点，避免了 Cloudflare 的拦截，实现了可靠的定时拉取；内置智能限流（TTL 缓存和退避）并附带可爱的像素水豚动画。

适合谁使用

经常在 Claude Code CLI 中使用 Claude 的 macOS 用户
喜欢实用桌面工具的 Übersicht 爱好者
希望实时监控 Claude 计划用量限制的开发者
对绕过 Cloudflare 访问 Anthropic 用量 API 感兴趣的人

典型使用场景

在桌面上直接监控 Claude 会话和每周用量限制
当用量接近阈值时获得颜色变化预警（黄/红）
会话过期时快速重新登录或刷新令牌
欣赏会随节拍晃动的像素水豚动画

项目优势

直接使用 Claude Code OAuth API（而非 claude.ai）避免 Cloudflare 拦截
内置限流机制：5 分钟 TTL 缓存 + 遭遇 429 时自动退避 15 分钟
利用刷新令牌自动续期，使小组件可持续运行数周
像素水豚动画采用纯 CSS steps()，几乎不占用 CPU

使用前须知

需要 macOS、Übersicht 和已登录的 Claude Code CLI
小组件绑定 Übersicht（非独立应用），无法在其他操作系统运行
依赖未公开的 OAuth 端点，可能随时变化而不另行通知

README 快速开始

Claude Usage — Desktop Widget (macOS / Übersicht)

การ์ดแสดง plan usage limits ของ Claude (session / weekly / per-model) เป็น widget บน desktop ของ Mac อัปเดตอัตโนมัติทุก ~10 นาที มีปุ่ม refresh ทันที, ล็อกเลือกจอ, ล็อกอิน/รีเฟรช token ในตัว — และมี น้อง CapyBeats 🎧 คาปิบาร่า pixel-art นั่งโยกอยู่บนหัวการ์ด

ทำงานได้เพราะดึงผ่าน OAuth endpoint ของ Claude Code (/api/oauth/usage) โดยตรง — ไม่ผ่าน claude.ai ที่ติด Cloudflare จึงยิงจาก background script ได้ (ดู ความรู้เบื้องหลัง)

✨ ฟีเจอร์

🟦 Progress bar ต่อ limit: session / weekly (ทุกโมเดล) / weekly per-model (สีน้ำเงิน → เหลืองเมื่อ ≥80% → แดงเมื่อ ≥95%)
⏱️ เวลา reset: session แสดง "รีเซ็ตใน Xh Ym", weekly แสดงวัน+เวลา (เวลาเครื่อง)
🏷️ ป้าย plan อัตโนมัติ (Max 20× / Max 5× / Pro …) อ่านจาก credential ของแต่ละคน
🎧 CapyBeats — คาปิบาร่า pixel-art 72 เฟรม โยกอยู่บนหัวการ์ด (CSS steps() ล้วน ไม่กิน CPU, ปรับขนาดได้ที่ CAPY_SCALE)
🛡️ กัน rate limit (429) ในตัว script — TTL cache 5 นาที (เรียกกี่ครั้งก็ยิง API จริงไม่เกิน 1 ครั้ง/TTL) และเจอ 429 จะพักยิง 15 นาทีเองอัตโนมัติ ระหว่างนั้นโชว์ค่าเดิม
🖱️ ลากย้ายได้ — จับที่แถบหัวการ์ด จำตำแหน่งไว้ (localStorage)
🖥️ รองรับหลายจอ — ปุ่ม 🖥️ เปิด dropdown เลือกจอที่จะให้ widget อยู่
🔄 ปุ่ม ↻ รีเฟรช — ดึงข้อมูลใหม่ทันที (--force ข้าม TTL cache แต่ไม่ฝ่า backoff 429) และไม่มีทางวาดทับข้อมูลดีด้วย error — ถ้าผลลัพธ์เพี้ยนจะคงค่าเดิมไว้เสมอ
🔑 ปุ่มล็อกอิน/รีเฟรช token — เปิด Terminal รัน claude เมื่อ session หลุด
💾 Cache/stale — ถ้า token หมดอายุ/เน็ตล่ม จะโชว์ค่าเดิม + ไฟเตือน แทนที่จะว่างเปล่า
✕ ย่อเป็น pill เล็ก — คลิก ✕ ยุบเหลือวงกลม % session, คลิกซ้ำกางคืน

📦 ความต้องการของระบบ

macOS (Apple Silicon หรือ Intel)
Claude Code CLI ติดตั้งและ ล็อกอินอยู่ (widget อ่าน OAuth token ที่มันเก็บ)
Übersicht (installer ติดตั้งให้ผ่าน Homebrew ได้)
python3 (มากับ macOS)

🚀 ติดตั้ง (เครื่องใหม่ / เพื่อนร่วมทีม)

git clone  claude-usage-widget
cd claude-usage-widget
bash install-claude-usage-widget.command      # หรือดับเบิลคลิกไฟล์นี้ใน Finder

installer จะ:

เช็ก/ติดตั้ง Übersicht (ผ่าน brew install --cask ubersicht)
copy claude-usage.jsx ไปโฟลเดอร์ widgets ของ Übersicht **พร้อมแก้ path สคริปต์ให้ตรงเครื่องอั

项目描述

Claude plan usage limits as a macOS desktop widget (Übersicht) — reads Claude Code's OAuth token, polls /api/oauth/usage, auto-refreshes token

claude-usage-widget