{"id":50380890,"url":"https://github.com/monska85/claude-usage","last_synced_at":"2026-05-30T12:01:19.289Z","repository":{"id":361116909,"uuid":"1251737493","full_name":"Monska85/claude-usage","owner":"Monska85","description":"CLI dashboard and GNOME Shell extension for monitoring Claude Code usage: utilization, tokens, costs, and rate-limit reset times.","archived":false,"fork":false,"pushed_at":"2026-05-29T08:00:04.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T09:27:05.514Z","etag":null,"topics":["anthropic","anthropic-claude","claude","claude-code","claude-code-usage","cli","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Monska85.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-27T21:41:38.000Z","updated_at":"2026-05-29T07:58:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Monska85/claude-usage","commit_stats":null,"previous_names":["monska85/claude-usage"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Monska85/claude-usage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monska85%2Fclaude-usage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monska85%2Fclaude-usage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monska85%2Fclaude-usage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monska85%2Fclaude-usage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Monska85","download_url":"https://codeload.github.com/Monska85/claude-usage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Monska85%2Fclaude-usage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33691312,"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-05-30T02:00:06.278Z","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","anthropic-claude","claude","claude-code","claude-code-usage","cli","go","golang"],"created_at":"2026-05-30T12:01:18.599Z","updated_at":"2026-05-30T12:01:19.274Z","avatar_url":"https://github.com/Monska85.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Usage Monitor\n\nCLI dashboard + GNOME Shell extension for monitoring Claude Code usage — utilization percentages, rate-limit reset times, token counts, and estimated costs.\n\n## How it works\n\nClaude Code has no public usage API. This tool polls the Anthropic API with a minimal 1-token Haiku request (~$0.000012/poll) and reads the rate-limit headers to determine your current utilization. Token and cost data is parsed from Claude Code's local JSONL conversation logs.\n\n## Features\n\n- **CLI dashboard** — colored tables showing utilization, tokens, and costs across configurable time periods\n- **GNOME Shell extension** — panel indicator with current (5h) and weekly (7d) utilization percentages, with detailed stats in dropdown menu\n- **Minimal polling cost** — ~$0.017/day, ~$0.52/month with 60s interval\n- **Single static binary** — no runtime dependencies, no Python, no venv\n- **Configurable** — YAML config for polling interval, display periods, cost visibility, color thresholds, model pricing overrides\n\n## Requirements\n\n- Go 1.23+ (build only)\n- Claude Code with valid credentials at `~/.claude/.credentials.json`\n- GNOME Shell 45–50 (for the extension)\n\n## Installation\n\n### Build and install everything\n\n```bash\nmake install\n```\n\nThis builds the binary, installs it to `~/.local/bin/claude-usage`, and copies the GNOME Shell extension.\n\n### Binary only\n\n```bash\nmake install-binary\n```\n\n### Extension only\n\n```bash\nmake install-gnome-extension\ngnome-extensions enable claude-usage@claude-code-usage\n```\n\n\u003e **Note:** On Wayland, you must log out and back in (or use a nested shell) for extension changes to take effect.\n\n## Usage\n\n### CLI\n\n```bash\n# Full dashboard with polling\nclaude-usage\n\n# Skip polling, use cached data\nclaude-usage --no-poll\n\n# Force poll even if cache is fresh\nclaude-usage --force-poll\n\n# Hide cost estimates\nclaude-usage --no-cost\n\n# Show specific period only (today, 7d, 30d, all)\nclaude-usage --period 7d\n\n# Poll and update cache silently (for scripting/cron)\nclaude-usage --poll-only\n\n# JSON status output (used by GNOME extension and other consumers)\nclaude-usage --status\n\n# Force a fresh API poll with status output\nclaude-usage --status --force-poll\n\n# Cache-only status, no API call (returns stale data if cache exists)\nclaude-usage --status --no-poll\n\n# Use custom config file\nclaude-usage --config /path/to/config.yaml\n```\n\n### GNOME Shell extension\n\nOnce enabled, the extension shows a panel indicator:\n\n```\nC:42%  W:67%\n```\n\n- **C** — Current period (5h window) utilization\n- **W** — Weekly period (7d window) utilization\n- Color-coded: green (\u003c80%), orange (80–89%), red (\u003e=90%)\n- Faded to 50% opacity when Claude Code is not running\n- Labels dimmed at 50% opacity when data is stale\n- Click for a dropdown with:\n  - Current/Weekly stats with reset times (same colors as panel)\n  - Stale data warning (orange) when applicable\n  - Claude Code process state: running (green) / not running (orange)\n  - Auth state when not valid: expired (orange) / missing (red)\n  - \"Refresh Now\" button\n  - Disclaimer noting data is estimated\n- Calls `claude-usage --status` every 30s; all logic lives in the CLI\n- \"Refresh Now\" uses `--status --force-poll` to trigger an API call\n- Binary lookup: checks `$PATH` first, falls back to `~/.local/bin/claude-usage`\n\n## Configuration\n\nDefault config location: `~/.config/claude-code-usage/config.yaml`\n\nSee [`config.default.yaml`](config.default.yaml) for all options:\n\n```yaml\napi:\n  enabled: true\n  stale_after: 60 # seconds — poll API if cache is older than this\n  model: claude-haiku-4-5-20251001\n  only_when_active: true # only poll when Claude Code is running\n\ndisplay:\n  show_cost: true\n  periods:\n    - today\n    - 7d\n    - 30d\n\ncolors:\n  green_below: 80 # percentage thresholds\n  orange_below: 90\n\ncache:\n  # path: /custom/path/quota.json  # default: ~/.cache/claude-code-usage/quota.json\n```\n\n## Testing the extension\n\nRequires `mutter-devkit` package (Arch: `mutter`):\n\n```bash\nmake test-gnome-extension\n```\n\nThis installs the extension and launches a nested GNOME Shell via `dbus-run-session gnome-shell --devkit --wayland`.\n\n## Uninstall\n\n```bash\nmake uninstall\n```\n\n## How polling works\n\n1. Sends a minimal API request: `max_tokens: 1`, `content: \".\"`, `temperature: 0` using `claude-haiku-4-5-20251001`\n2. Reads `x-ratelimit-*` response headers for utilization and reset times\n3. Writes results to a JSON cache at `~/.cache/claude-code-usage/quota.json`\n4. GNOME extension calls `claude-usage --status` every 30s, which returns JSON with raw data (percentages, reset times, colors, stale flag)\n5. The CLI handles cache freshness internally — if cache is warm, it returns cached data without polling\n6. The extension is a pure renderer — it formats display text and handles the stale indicator locally\n\n## Cost note\n\nCost values shown are **API-equivalent estimates** based on token counts and published pricing. If you're on a Claude subscription (Pro/Team/Enterprise), usage is included in your plan — the costs shown represent what the equivalent API usage would cost, not actual charges.\n\n## License\n\n[GPL-3.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonska85%2Fclaude-usage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonska85%2Fclaude-usage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonska85%2Fclaude-usage/lists"}