Why it is worth attention

It reverse-engineers the Claude Code CLI's OAuth endpoint to fetch usage data without hitting Cloudflare, enabling reliable background polling, and includes clever self-rate-limiting (TTL cache and backoff) plus a charming pixel-art capybara.

Who it is for

macOS users who frequently use Claude in Claude Code CLI
Übersicht widget enthusiasts looking for practical desktop tools
Developers wanting to monitor their Claude API plan limits in real time
Anyone curious about bypassing Cloudflare for Anthropic's usage API

Use cases

Keep an eye on Claude session and weekly usage limits directly on the desktop
Get color-coded warnings (yellow/red) when usage approaches thresholds
Quickly re-login or refresh the token when the session expires
Enjoy a decorative pixel-art capybara that bounces to the beat

Strengths

Directly uses Claude Code OAuth API (not claude.ai) to avoid Cloudflare blocks
Self-contained rate limiting: 5-minute TTL cache + 15-minute backoff on 429 errors
Automatic token refresh via refresh token, keeping the widget alive for weeks
Pixel-art capybara animation uses pure CSS steps() with negligible CPU impact

Considerations

Requires macOS, Übersicht, and an active Claude Code CLI login
Widget is tied to Übersicht (not a standalone app) and cannot run on other OS
Dependence on the undocumented OAuth endpoint which may change without notice

README quick start

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 สคริปต์ให้ตรงเครื่องอั

Description

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

Related repositories

Similar projects matched by category, topics, and programming language.

jamesob

Featured

local-llm

A comprehensive guide for building and configuring a high-end local machine to run state-of-the-art LLMs, with detailed hardware choices, BIOS tuning, and Docker-based model serving.

AI & Machine LearningLarge Language Models

1,660

bjan

Featured

claudemux

Claudemux is a lightweight, dependency-minimal message bus that lets multiple Claude Code sessions communicate in real-time over tmux, enabling one session to ask another a question and receive the answer without manual intervention.

AI & Machine LearningAI Agents

AARomanov1985

Audio-Cassette-Simulation

A set of bash scripts using ffmpeg to simulate vintage cassette tape audio profiles with noise, wow/flutter, bandwidth limits, and EQ.

Shell

373