{"id":50855714,"url":"https://github.com/thanhhaudev/kwota","last_synced_at":"2026-06-14T18:03:21.433Z","repository":{"id":364261759,"uuid":"1221738932","full_name":"thanhhaudev/kwota","owner":"thanhhaudev","description":"Token usage tracker for AI coding assistants","archived":false,"fork":false,"pushed_at":"2026-06-12T10:31:52.000Z","size":2314,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T11:05:33.333Z","etag":null,"topics":["claude","macos","swift","utilities"],"latest_commit_sha":null,"homepage":"","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/thanhhaudev.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-04-26T16:09:34.000Z","updated_at":"2026-06-12T10:31:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thanhhaudev/kwota","commit_stats":null,"previous_names":["thanhhaudev/kwota"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/thanhhaudev/kwota","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanhhaudev%2Fkwota","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanhhaudev%2Fkwota/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanhhaudev%2Fkwota/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanhhaudev%2Fkwota/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thanhhaudev","download_url":"https://codeload.github.com/thanhhaudev/kwota/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thanhhaudev%2Fkwota/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34331819,"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-14T02:00:07.365Z","response_time":62,"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":["claude","macos","swift","utilities"],"created_at":"2026-06-14T18:03:20.733Z","updated_at":"2026-06-14T18:03:21.425Z","avatar_url":"https://github.com/thanhhaudev.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kwota\n\nToken usage tracker for AI coding assistants. Lives in the menu bar; auto-keeps your Mac awake while agents are working, and tracks caches on your machine.\n\nHobby project, built for fun. macOS 14.0+ to run, Xcode 16+ to build.\n\n![Kwota preview](assets/preview.gif)\n\n## Providers\n\n| Provider    | Tracked                                              | Source                                                                          |\n| ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- |\n| Claude Code | 5-hour session, weekly limit, per-model breakdown    | `api.anthropic.com/api/oauth/usage` (OAuth via Claude CLI auth) + `~/.claude/projects/**/*.jsonl` |\n| Codex       | 5-hour + weekly buckets                              | `wham/usage`                                                                    |\n| Antigravity | Credit pools + per-model quotas                      | local Connect-RPC `GetUserStatus`                                               |\n\n## Build\n\n```bash\nmake build                       # debug\nmake run                         # build + launch\nmake release-app                 # release build → build/Release/Kwota.app\nmake test                        # unit tests (~90s, parallel)\nmake test-only SUITE=\u003cName\u003e      # one suite, no rebuild\nmake test-all                    # include UI tests (serial)\nmake help                        # all targets\n```\n\nDerivedData is shared at `~/Library/Developer/Xcode/DerivedData/Kwota-shared`. The UI test target is excluded from `make test` by default.\n\n## Install\n\nThe app runs without signing setup. To enable **system-cache cleaning** (needs a root helper):\n\n1. Get your Apple Team ID and put it in `Local.xcconfig` (`make build` creates it\n   from `.example` if missing). No paid Apple Developer Program needed:\n   1. Xcode → Settings → Accounts → `+` → sign in with your Apple ID. A free\n      account works — Xcode creates a \"Personal Team\" for it.\n   2. Open `Kwota/Kwota.xcodeproj`, select the **Kwota** target →\n      **Signing \u0026 Capabilities** → pick your team in the **Team** dropdown.\n   3. Xcode writes the team ID into the project file. Read it back:\n      `grep -m1 DEVELOPMENT_TEAM Kwota/Kwota.xcodeproj/project.pbxproj`\n      — the 10-character value is your Team ID.\n   4. Set `DEVELOPMENT_TEAM = \u003cthat ID\u003e` in `Local.xcconfig`, then revert the\n      project file: `git checkout -- Kwota/Kwota.xcodeproj` (the team belongs\n      in `Local.xcconfig`, which is gitignored).\n2. `make release-app`, drag `build/Release/Kwota.app` to `/Applications`.\n3. Settings → Cache → Privileged helper → Install. Approve in System Settings → General → Login Items \u0026 Extensions.\n\nIf `Install` errors after a previous attempt: `sudo sfltool resetbtm`.\n\n## Tabs\n\n**Usage** — per-provider quota view (see the Providers table above). Each provider gets a session chart with an `avg` reference line (typical % at the same point in past cycles) and a pace hint (\"on track\", \"above typical\", etc.). A Free-plan overlay shows for Claude accounts with no paid subscription.\n\n**Awake** — toggle `caffeinate` (manual / auto / battery-aware). Below it: a multi-provider activity chart of recent agent replies. The chart shades each awake interval by mode — auto (green) or manual (blue). Battery (orange) shows up as the status dot in the card, menu-bar icon, and Settings row when auto is blocked by a low-battery threshold.\n\n**Cache** — tracks caches across your machine: developer tooling (Xcode DerivedData, npm / bun / yarn / pnpm, pip, Homebrew, JetBrains, VS Code, Cursor), iOS Simulator / DeviceSupport, the macOS Icon services cache, generic `~/.cache`, and more. Each row shows a size breakdown and an AI evaluation. System-wide caches that need root also appear here once the privileged helper is installed.\n\n## How polling works\n\nOne self-rescheduling timer:\n- Popover open: ~60s\n- Popover closed: ~10min\n- ±20% jitter on every interval\n- A 429 sets a per-provider back-off floor (from `Retry-After`); other providers keep polling\n\nManual refresh (chart button or \"Refresh\" shortcut) respects the same back-off and a short anti-spam throttle.\n\n## How token data is collected\n\nKwota never invokes `claude`, `codex`, or `agy` to read usage — that would burn quota.\n\nThe Cache tab's \"AI evaluation\" is the one feature that does spawn `claude -p` (Anthropic blocks 3rd-party API access). It uses your normal subscription quota; Kwota tells you when it happens.\n\n## How the avg line is computed\n\nKwota stores raw `(timestamp, % used)` samples and segments them into completed cycles — 5-hour cycles for the session view, 7-day cycles for the weekly view.\n\nA cycle ends when the next sample's value drops by ≥5 percentage points (smaller drops are server-side rounding noise; a real reset is ~95+). The trailing in-progress cycle is excluded so the line compares against finished history, not a partial sample.\n\nFor any elapsed time `t` in the current cycle, `avg(t)` is the mean of `value(t)` across past cycles — \"what % were you typically at, this far in\". The chart draws it as a reference line alongside the current cycle's series; the pace hint reads \"on track\" / \"above typical\" / etc. by comparing the current point against `avg(t)`.\n\n## How the session/week chart renders\n\nClaude and Codex share the same chart. Two views:\n\n- **Session** — bars per hour of the current 5-hour cycle. The latest bar is the focal bar; an extra ghost bar projects the next hour from up to the last 3 hour-to-hour deltas.\n- **Week** — bars per day of the current 7-day cycle.\n\nEach bar's color comes from its own value — green → yellow → red as it approaches the limit. The session's focal bar adds a slow \"warm pulse\" when the pace is heavy. The dashed green `avg` line (toggleable) sits over the bars. Before the first successful fetch, the chart shows \"Waiting for first fetch…\".\n\n## Notes\n\n- Sandbox-disabled. Launches `/usr/bin/caffeinate`, probes `claude --version` / `codex --version` / `agy --version`, holds IOKit power assertions, and reads `~/.claude/`, `~/.codex/`, and `~/.gemini/antigravity*/` directly. Distribute as a Developer-ID-signed `.app`, not via the Mac App Store.\n- `claude` / `codex` / `agy` are resolved against an augmented PATH that includes `/opt/homebrew/bin` and `/usr/local/bin`.\n- No remote backend — only reads provider files and APIs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthanhhaudev%2Fkwota","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthanhhaudev%2Fkwota","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthanhhaudev%2Fkwota/lists"}