{"id":51294371,"url":"https://github.com/flukelaster/llm-usage-widget","last_synced_at":"2026-06-30T13:02:06.794Z","repository":{"id":366054778,"uuid":"1273232484","full_name":"flukelaster/LLM-Usage-Widget","owner":"flukelaster","description":"macOS menu-bar \u0026 Windows system-tray app showing real-time usage limits for Claude, Codex \u0026 GitHub Copilot.","archived":false,"fork":false,"pushed_at":"2026-06-20T05:04:22.000Z","size":4834,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T05:10:10.920Z","etag":null,"topics":["anthropic","apple-silicon","avalonia","claude","codex","cross-platform","csharp","dotnet","github-copilot","llm","macos","menu-bar-app","menubar","oauth","openai","swift","swiftui","system-tray","usage-tracker","windows"],"latest_commit_sha":null,"homepage":"https://github.com/flukelaster/LLM-Usage-Widget/releases/latest","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flukelaster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-18T10:24:49.000Z","updated_at":"2026-06-20T05:04:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/flukelaster/LLM-Usage-Widget","commit_stats":null,"previous_names":["flukelaster/llm-usage-widget"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/flukelaster/LLM-Usage-Widget","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flukelaster%2FLLM-Usage-Widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flukelaster%2FLLM-Usage-Widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flukelaster%2FLLM-Usage-Widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flukelaster%2FLLM-Usage-Widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flukelaster","download_url":"https://codeload.github.com/flukelaster/LLM-Usage-Widget/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flukelaster%2FLLM-Usage-Widget/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34967636,"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","apple-silicon","avalonia","claude","codex","cross-platform","csharp","dotnet","github-copilot","llm","macos","menu-bar-app","menubar","oauth","openai","swift","swiftui","system-tray","usage-tracker","windows"],"created_at":"2026-06-30T13:02:02.001Z","updated_at":"2026-06-30T13:02:06.782Z","avatar_url":"https://github.com/flukelaster.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/cover.png\" alt=\"LLM Usage Widget — real-time usage limits for Claude, Codex and GitHub Copilot, live in your macOS menu bar\" width=\"100%\"\u003e\n\n\u003ch1\u003eLLM Usage Widget\u003c/h1\u003e\n\n\u003cp\u003e\u003cstrong\u003eA menu-bar \u0026amp; system-tray app for \u003cb\u003emacOS\u003c/b\u003e and \u003cb\u003eWindows\u003c/b\u003e, showing real-time\nusage limits for your main LLM tools — \u003ca href=\"https://claude.ai\"\u003eClaude\u003c/a\u003e,\n\u003ca href=\"https://chatgpt.com\"\u003eCodex\u003c/a\u003e, and \u003ca href=\"https://github.com/features/copilot\"\u003eGitHub Copilot\u003c/a\u003e.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp\u003eIt surfaces your usage windows the way Claude Desktop does: a glanceable percentage in the\nmenu bar (or Windows tray), and a click-away popover with usage bars, reset countdowns, and near-limit alerts.\u003c/p\u003e\n\n[![Download for macOS](https://img.shields.io/badge/Download-macOS%20.dmg-2EA043?style=for-the-badge\u0026logo=apple\u0026logoColor=white)](https://github.com/flukelaster/LLM-Usage-Widget/releases/latest/download/LLM-Usage-Widget.dmg)\n\u0026nbsp;\n[![Download for Windows](https://img.shields.io/badge/Download-Windows%20.exe-2563EB?style=for-the-badge\u0026logo=windows\u0026logoColor=white)](https://github.com/flukelaster/LLM-Usage-Widget/releases/latest/download/LLM-Usage-Widget-windows-x64.exe)\n\n![macOS 14+](https://img.shields.io/badge/macOS-14%2B-0B1120?logo=apple\u0026logoColor=white)\n![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-arm64-243049)\n![Windows 10/11](https://img.shields.io/badge/Windows-10%2F11%20x64-0B1120?logo=windows\u0026logoColor=white)\n![Swift 6](https://img.shields.io/badge/Swift-6-FA7343?logo=swift\u0026logoColor=white)\n![.NET 10](https://img.shields.io/badge/.NET-10%20%2B%20Avalonia-512BD4?logo=dotnet\u0026logoColor=white)\n\n\u003csub\u003emacOS is native SwiftUI; the **Windows** build is .NET 10 + Avalonia — see [`windows/`](windows/README.md). Both share the same providers and design.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n---\n\n## Features\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd width=\"54%\" valign=\"top\"\u003e\n\nClick the menu-bar / tray gauge to see, per provider:\n\n- **5-hour and weekly usage bars**, each with the percentage used and a reset countdown.\n- **Threshold colors** — green below 60%, amber 60–85%, red above 85%.\n- **Plan badge** (Max / Pro / Plus …) and an *up to date / rate-limited / stale* status.\n- **A live percentage in the menu bar** — by default the provider closest to its limit, or pin a specific provider in Settings.\n- **Near-limit notifications** when any window crosses 90% (once per window, per reset cycle).\n- **In-app OAuth** (PKCE) — tokens are stored only in your OS credential store (macOS Keychain / Windows DPAPI).\n\n\u003c/td\u003e\u003ctd width=\"46%\" valign=\"top\" align=\"center\"\u003e\n\n\u003ctable align=\"center\"\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cimg src=\"docs/screenshot.png\" alt=\"macOS popover\" width=\"168\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003emacOS\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cimg src=\"docs/windows-screenshot.png\" alt=\"Windows popover\" width=\"168\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eWindows\u003c/b\u003e\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n## Installation\n\nGrab the latest build from the\n[**Releases**](https://github.com/flukelaster/LLM-Usage-Widget/releases/latest) page:\n\n- **macOS** — download `LLM-Usage-Widget.dmg` and drag the app into **Applications**. Requires\n  macOS 14 (Sonoma) or later on Apple Silicon. It's menu-bar-only (`LSUIElement`, no Dock icon) —\n  look for the gauge in the top-right of the menu bar.\n- **Windows** — download `LLM-Usage-Widget-windows-x64.exe` and run it. Requires Windows 10/11 (x64).\n  It's self-contained (no .NET install needed) and lives in the system tray — click the gauge for the\n  popover. See [`windows/`](windows/README.md) for details.\n\n\u003e [!NOTE]\n\u003e Both builds are ad-hoc / unsigned, so the **first launch** needs a one-time confirmation: on macOS,\n\u003e right-click the app → **Open**, then confirm (see [Distribution](#distribution)); on Windows,\n\u003e SmartScreen may warn — choose **More info → Run anyway**.\n\n## Building from source\n\n**Requirements:** macOS 14 (Sonoma) or later, and a Swift 6 toolchain. The Command Line Tools are\nsufficient — full Xcode is not required.\n\n```bash\n./Scripts/run.sh                   # build (debug) → package UsageWidget.app → launch\n./Scripts/package_app.sh release   # build the release .app bundle only\n```\n\n## Signing in\n\nOpen the popover and click **Sign in** on a provider card:\n\n| Provider | Authentication flow |\n|---|---|\n| **Codex** | Opens your browser to OpenAI; a local listener on `127.0.0.1:1455` captures the redirect automatically — nothing to paste. |\n| **Claude** | Opens your browser to Anthropic, which shows a code (`abc123#xyz`). Paste it back into the card. Anthropic rejects arbitrary loopback redirects, so this paste step is required. |\n| **Copilot** | Uses GitHub's device flow: the card shows a short code; enter it at `github.com/login/device` (opened for you) and the app finishes automatically. |\n\nProviders (enable / disable, sign out), poll interval, **menu-bar focus and display**, near-limit\nnotifications, and **Launch at login** are all managed from **Settings** in the footer of the popover.\n\n## How it works\n\nEach provider exposes the same usage endpoint its own first-party client uses:\n\n| Provider | Endpoint | Notes |\n|---|---|---|\n| Claude | `GET api.anthropic.com/api/oauth/usage` | The endpoint Claude Code's `/usage` uses. Requires the `anthropic-beta` header and a `claude-code/\u003cver\u003e` User-Agent. Rate-limits hard, so it is polled at most every 5 minutes with exponential backoff. |\n| Codex | `GET chatgpt.com/backend-api/wham/usage` | Returns the primary (5-hour) and secondary (weekly) windows. |\n| Copilot | `GET api.github.com/copilot_internal/user` | Monthly premium-request quota (`quota_snapshots`) and reset date. |\n\nClaude's `/usage` endpoint carries no plan, so the **Max / Pro** badge comes from a separate profile\nendpoint (`GET api.anthropic.com/api/oauth/profile`) that is fetched once and cached on the token.\n\nThe last-good snapshot is cached to `~/Library/Application Support/com.flukelaster.usagewidget/`,\nso the popover shows data instantly and never blanks out on a failed refresh.\n\n\u003e [!WARNING]\n\u003e These endpoints and the first-party OAuth client IDs are **undocumented and unofficial**, and may\n\u003e change without notice. The app reads only **your own** subscription usage and never automates\n\u003e inference. Use is a gray area under each vendor's terms. It degrades gracefully if an endpoint\n\u003e changes — falling back to cached data with a clear error, never a crash.\n\nGemini and Cursor were evaluated but deferred: Gemini's individual CLI usage API is mid-migration to\nAntigravity, and Cursor requires reading the editor's local SQLite with full-disk access and has no\nper-user official API.\n\n## Development\n\n```bash\nswift build                                   # compile\n.build/debug/UsageWidget --check              # run the logic self-checks (parsing, PKCE, backoff, …)\n.build/debug/UsageWidget --snapshot out.png   # render the popover UI to a PNG (DEBUG)\n```\n\nThe Command Line Tools toolchain ships neither XCTest nor swift-testing, so the test suite is an\nin-process self-check run via `--check`. Add an XCTest or swift-testing target once full Xcode is\ninstalled if desired.\n\nRegenerate the app icon after design tweaks with `./Scripts/make_icon.sh` (renders the SwiftUI icon\nto `Resources/AppIcon.icns`). Regenerate this README's cover image with `node Scripts/make_cover.mjs`.\n\n## Architecture\n\n```\nSources/UsageWidget/\n  App/         @main entry, AppDelegate, composition root, snapshot/self-check runners\n  MenuBar/     menu-bar label and popover root\n  Domain/      UsageProvider protocol and unified models (LimitWindow, ProviderUsage, …)\n  Providers/   Claude/, Codex/, Copilot/ — OAuth clients, usage fetchers, orchestration\n  Auth/        PKCE, Keychain, TokenStore, loopback OAuth server\n  Engine/      UsageStore (@Observable), RefreshScheduler, BackoffPolicy, SnapshotCache\n  Settings/    SettingsModel/View, LaunchAtLogin (SMAppService)\n  Views/       design tokens, provider card, limit-window bar, states, Claude mascot\n  Diagnostics/ SelfChecks\n```\n\n## Distribution\n\nBuild a distributable disk image:\n\n```bash\n./Scripts/release.sh      # → dist/LLM-Usage-Widget.dmg (drag-to-Applications installer)\n```\n\nThe build is **arm64 (Apple Silicon)** and **ad-hoc signed** — there is no Apple Developer ID on\nthis machine, and a universal arm64 + x86_64 build would require full Xcode (`xcbuild`). It runs\nfine when shared, but the **first launch on another Mac** needs a one-time Gatekeeper bypass:\n\n- Right-click the app and choose **Open** (then confirm), or\n- `xattr -dr com.apple.quarantine \"/Applications/UsageWidget.app\"`\n\nFor a clean, no-warning build — recommended if you distribute widely — get an Apple Developer ID\n($99/year) and notarize. `Scripts/notarize.sh` performs the Developer-ID signing, hardened runtime,\n`notarytool` submission, and staple:\n\n```bash\nDEV_ID=\"Developer ID Application: Your Name (TEAMID)\" \\\nAPPLE_ID=\"you@example.com\" TEAM_ID=\"TEAMID\" APP_PW=\"app-specific-password\" \\\n./Scripts/notarize.sh        # then ./Scripts/release.sh to wrap it in a .dmg\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflukelaster%2Fllm-usage-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflukelaster%2Fllm-usage-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflukelaster%2Fllm-usage-widget/lists"}