{"id":51293314,"url":"https://github.com/huanchong-99/claude-usage-assistant","last_synced_at":"2026-06-30T12:30:23.536Z","repository":{"id":364833133,"uuid":"1269381094","full_name":"huanchong-99/claude-usage-assistant","owner":"huanchong-99","description":"Real-time Claude Code usage-limit card for Windows, macOS, and Linux — 5h/7d (and per-model) windows with local-timezone reset times, system tray, color-coded. 中文/English.","archived":false,"fork":false,"pushed_at":"2026-06-14T17:14:40.000Z","size":95,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T18:23:12.798Z","etag":null,"topics":["anthropic","claude","claude-code","desktop-widget","linux","macos","rate-limit","tkinter","usage-monitor","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/huanchong-99.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T16:37:06.000Z","updated_at":"2026-06-14T17:16:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/huanchong-99/claude-usage-assistant","commit_stats":null,"previous_names":["huanchong-99/claude-usage-assistant"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/huanchong-99/claude-usage-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanchong-99%2Fclaude-usage-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanchong-99%2Fclaude-usage-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanchong-99%2Fclaude-usage-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanchong-99%2Fclaude-usage-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/huanchong-99","download_url":"https://codeload.github.com/huanchong-99/claude-usage-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanchong-99%2Fclaude-usage-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34967614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-code","desktop-widget","linux","macos","rate-limit","tkinter","usage-monitor","windows"],"created_at":"2026-06-30T12:30:21.421Z","updated_at":"2026-06-30T12:30:23.508Z","avatar_url":"https://github.com/huanchong-99.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Usage Assistant\n\nA tiny, always-on-top desktop card for **Windows, macOS, and Linux** that shows your **Claude Code** usage limits in real time — the 5-hour and 7-day rolling windows (plus per-model windows such as 7-day Sonnet / Opus), each with its **reset time in your local timezone**. Includes a system-tray indicator.\n\nIt does **not** bypass any limit — it just makes the official numbers visible so you can pace yourself.\n\nEnglish | [简体中文](README.zh-CN.md)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/card.png\" width=\"430\" alt=\"Claude Usage Assistant — the live card\"\u003e\u003cbr\u003e\n  \u003csub\u003eThe live card: 5-hour / 7-day / per-model windows, color-coded, each with its real reset time in your local timezone.\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/windows.png\" width=\"300\" alt=\"The tray shows a window's percent right in the taskbar\"\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"assets/menu.png\" width=\"300\" alt=\"Right-click menu\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\u003cb\u003eLeft:\u003c/b\u003e the tray icon shows your chosen window's % right in the taskbar (the green \u003cb\u003e17%\u003c/b\u003e at the bottom-left), and the card can list every window your account exposes — here 5-hour, 7-day, and 7-day · Sonnet. \u0026nbsp;·\u0026nbsp; \u003cb\u003eRight:\u003c/b\u003e the menu lets you toggle \u003cb\u003eeach window on the card individually\u003c/b\u003e and pick \u003cb\u003ewhich one the tray reflects\u003c/b\u003e.\u003c/sub\u003e\n\u003c/p\u003e\n\n## Features\n\n- **Live 5-hour \u0026 7-day usage** (and any other windows your account exposes), color-coded green / amber / red.\n- **Real reset time, your timezone** — shown as a local clock like `今天 04:19` / `06-17 21:59`, derived from your system timezone (UTC+8, UTC+7, …) automatically. A live system clock sits in the footer.\n- **System-tray icon** showing a chosen window's percentage with a `%` sign (default: 5-hour). Left-click toggles the card; hover for a full breakdown.\n- **Frameless, draggable, always-on-top card.** Resize by mouse-wheel, by dragging the window edges/corners, or via the menu.\n- **Menu** (right-click or the `☰` button): **show or hide each window on the card individually** (5-hour, 7-day, 7-day · Sonnet, …), pick **which one the tray reflects**, plus zoom, opacity, and reset-display mode (clock vs. countdown).\n- Remembers position, size, opacity, and preferences. **Single-instance guard.** Optional **autostart**.\n- **Cross-platform** — one file runs on Windows, macOS, and Linux; on macOS the token is read from the **Keychain** automatically, and the transparent look adapts per OS.\n- Pure standard-library **tkinter** UI — no heavy UI framework. A single ~960-line file, fully auditable.\n\n## Security \u0026 privacy\n\n- Reads your existing Claude Code OAuth token **read-only** — from `~/.claude/.credentials.json` on Windows/Linux, or the **macOS Keychain** (via `security find-generic-password`, read-only) on macOS.\n- The token is placed **only** in the `Authorization` header and sent **only** to **`api.anthropic.com`** — the same call Claude Code itself makes.\n- **No telemetry, no third-party servers.** Nothing is written out, cached, or uploaded anywhere, except a local `card_state.json` holding window position and UI preferences (it contains **no** credentials).\n- It only **displays** official usage; it does **not** bypass, modify, or work around any limit.\n- All of it lives in [`quota_card.py`](quota_card.py) — read every line.\n\n## Disclaimer\n\nThis tool reads usage from `https://api.anthropic.com/api/oauth/usage`, an **undocumented internal endpoint** used by Claude Code. It is not a public/official API and **may change or stop working at any time**. The endpoint URL and field names are kept as constants near the top of `quota_card.py` so a fix is a one-line change. This project is **not affiliated with or endorsed by Anthropic**.\n\n## Platform support\n\n|  | Windows | macOS | Linux |\n|---|:---:|:---:|:---:|\n| Live usage \u0026 data | ✅ | ✅ (token via Keychain) | ✅ |\n| Transparent rounded card | ✅ color-key | ✅ `systemTransparent` | ▢ opaque card (square corners) |\n| System tray | ✅ | ✅ | ✅ with a tray host |\n| High-DPI / Retina scaling | ✅ | ✅ | ✅ |\n| Single-instance guard | ✅ mutex | ✅ file lock | ✅ file lock |\n\nOne file, no per-OS build step. On Linux the card falls back to an opaque (square-cornered) look because X11 has no color-key transparency — everything else works the same. Set `QUOTA_CARD_OPAQUE=1` to force that opaque look on any OS.\n\n## Requirements\n\n- **Windows 10/11, macOS, or Linux**\n- Python 3.10+\n- [`requests`](https://pypi.org/project/requests/) (required)\n- [`pystray`](https://pypi.org/project/pystray/) + [`Pillow`](https://pypi.org/project/pillow/) (optional — for the system tray; the app degrades to card-only if missing)\n- You must have signed in to Claude Code at least once (so the token exists in `~/.claude/.credentials.json`, or in the macOS Keychain).\n- **Linux:** a compositing window manager (the default on GNOME/KDE) for the translucency; the tray needs a system-tray / AppIndicator host.\n\n## Install \u0026 run\n\n```sh\npip install requests pystray pillow\n\npython quota_card.py     # Windows\npython3 quota_card.py    # macOS / Linux\n```\n\n- **Windows:** or double-click **`启动卡片.bat`** (launches with no console window).\n- **macOS / Linux:** or run **`./start.sh`** (first time: `chmod +x start.sh`).\n\nVerify the data pull without opening the UI (add `--check`):\n\n```sh\npython quota_card.py --check     # macOS/Linux: python3 quota_card.py --check\n```\n\n## Deploy from scratch\n\n1. Install **Python 3.10+** — [python.org](https://www.python.org/downloads/) (on Windows tick **\"Add python.exe to PATH\"**; on macOS/Linux it's often preinstalled, or use Homebrew / your package manager).\n2. Clone the repo and enter it:\n   ```sh\n   git clone https://github.com/huanchong-99/claude-usage-assistant\n   cd claude-usage-assistant\n   ```\n3. Install dependencies:\n   ```sh\n   pip install requests pystray pillow\n   ```\n4. Make sure you have signed in to **Claude Code** at least once (so the token exists in `~/.claude/.credentials.json`, or in the macOS Keychain).\n5. Run it:\n   ```sh\n   python quota_card.py        # Windows  (or double-click 启动卡片.bat)\n   python3 quota_card.py       # macOS / Linux  (or ./start.sh)\n   ```\n6. *(Optional)* Autostart on boot — see [Autostart](#autostart-optional) below.\n\n## One-paste AI setup\n\nDon't want to do it by hand? Paste the block below to an AI coding assistant (e.g. **Claude Code**) and it will set everything up for you:\n\n```text\nWhen you read this, you are an AI coding assistant. Please deploy \"Claude Usage Assistant\" on this machine (it supports Windows, macOS, and Linux — detect the OS first):\n1. git clone https://github.com/huanchong-99/claude-usage-assistant and cd into the folder.\n2. Detect Python (3.10+) and install dependencies: pip install requests pystray pillow\n3. Confirm I have signed in to Claude Code (token in ~/.claude/.credentials.json, or the macOS Keychain); if not, tell me to run `claude` and log in first.\n4. Run the app (python quota_card.py on Windows, python3 quota_card.py on macOS/Linux) and verify the card shows my usage; if it errors, diagnose and fix it.\n5. Ask whether I want it to start automatically on boot; if yes, set it up the right way for my OS (Windows: a shortcut in shell:startup; macOS: a Login Item or LaunchAgent; Linux: a ~/.config/autostart entry).\nReport back in my language when done.\n```\n\n## Controls\n\n- **Drag** the card to move it (position is remembered).\n- **Mouse-wheel** to zoom · **drag window edges/corners** to resize · **Ctrl + wheel** to fine-tune opacity.\n- **Top bar:** `▲` keep-on-top · `☰` menu · `↻` refresh · `✕` quit.\n- **Menu** (right-click or `☰`): Refresh · **Card items** (tick each window — 5-hour / 7-day / 7-day · Sonnet … — to show or hide it on the card) · **Tray item** (which window's % the tray shows) · Zoom · Opacity · Reset display · Keep on top · Hide to tray · Quit.\n- **Tray icon:** shows the selected window's `%`; left-click toggles the card; right-click for the menu.\n\nBar colors: green `\u003c 50%`, amber `50–80%`, red `≥ 80%`.\n\n## Configuration\n\nConstants near the top of `quota_card.py`:\n\n- `REFRESH_INTERVAL` — auto-refresh seconds (default `60`).\n- `API_URL_USAGE` and the field names — edit here if the endpoint ever changes.\n\nPreferences (position, zoom, opacity, shown items, tray item, reset mode) are saved to `card_state.json`.\n\n**Environment variables:**\n\n- `QUOTA_CARD_OPAQUE=1` — force an opaque, square-cornered card on any OS (handy on Linux/macOS if the transparent corners ever render oddly).\n- `CLAUDE_CONFIG_DIR` — if you point Claude Code at a custom config dir, the app honors it too.\n\n## Autostart (optional)\n\n- **Windows:** press `Win + R`, type `shell:startup`, and drop a shortcut to `启动卡片.bat` (or to `pythonw.exe \"…\\quota_card.py\"`) into that folder.\n- **macOS:** add a **Login Item** (System Settings → General → Login Items → ＋, pick `start.sh`), or install a LaunchAgent plist that runs `python3 …/quota_card.py`.\n- **Linux:** drop a `.desktop` file into `~/.config/autostart/` whose `Exec=` runs `python3 /path/to/quota_card.py` (or `/path/to/start.sh`).\n\n## Friend Links\n\n- [LINUX DO](https://linux.do/) — a community for developers and tech enthusiasts.\n\n## Credits\n\n- Data approach referenced from [jens-duttke/usage-monitor-for-claude](https://github.com/jens-duttke/usage-monitor-for-claude).\n- The official `rate_limits` field is documented in the [Claude Code status line docs](https://code.claude.com/docs/en/statusline).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuanchong-99%2Fclaude-usage-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuanchong-99%2Fclaude-usage-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuanchong-99%2Fclaude-usage-assistant/lists"}