{"id":51348763,"url":"https://github.com/pickforge/pickgauge","last_synced_at":"2026-07-02T14:14:02.615Z","repository":{"id":362799681,"uuid":"1257483061","full_name":"pickforge/pickgauge","owner":"pickforge","description":"Local AI-usage visibility from the tray. Tracks Codex and Claude Code usage, privacy-first.","archived":false,"fork":false,"pushed_at":"2026-06-29T15:43:15.000Z","size":6187,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-29T17:29:00.706Z","etag":null,"topics":["ai-usage","claude-code","codex","privacy-first","rust","svelte","tauri","tray"],"latest_commit_sha":null,"homepage":"https://pickforge.dev","language":"Rust","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/pickforge.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":"docs/security/browser-profile-login-inspection.md","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-02T18:11:17.000Z","updated_at":"2026-06-29T15:41:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pickforge/pickgauge","commit_stats":null,"previous_names":["pickforge/ai-usage-tray","pickforge/pickgauge"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/pickforge/pickgauge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pickforge%2Fpickgauge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pickforge%2Fpickgauge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pickforge%2Fpickgauge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pickforge%2Fpickgauge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pickforge","download_url":"https://codeload.github.com/pickforge/pickgauge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pickforge%2Fpickgauge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35050378,"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-07-02T02:00:06.368Z","response_time":173,"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":["ai-usage","claude-code","codex","privacy-first","rust","svelte","tauri","tray"],"created_at":"2026-07-02T14:14:01.843Z","updated_at":"2026-07-02T14:14:02.597Z","avatar_url":"https://github.com/pickforge.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/branding/pickgauge-lockup-horizontal.svg\" alt=\"PickGauge\" width=\"560\"\u003e\n\u003c/p\u003e\n\n# PickGauge\n\nA fuel gauge for your AI subscriptions. PickGauge is a privacy-conscious Linux tray app that tracks remaining Codex and Claude Code usage — keeping quota awareness visible without storing passwords, uploading account data, or pretending best-effort estimates are exact.\n\nPickForge builds the app. PickGauge tells you how much agent fuel is left while you do it.\n\nLocal-first. Open source. Built for people who ship.\n\n\u003e **Status:** Tauri/Svelte desktop app with a branded dashboard, usage history, floating button, sound cues, persisted settings, tray wiring, app icons, and release automation. Web providers remain opt-in and await authenticated validation.\n\n## Install\n\nRelease artifacts are built from `main` by GitHub Actions: Linux AppImage, Windows installers, macOS Intel and Apple Silicon builds. Download the latest from [Releases](https://github.com/pickforge/pickgauge/releases/latest). PickGauge is still **Linux/KDE-first** — Linux is the tested platform; the Windows and macOS builds are produced automatically but currently **untested**; experience reports are welcome.\n\nOn CachyOS/Arch-like systems, local AppImage bundling can fail because the linuxdeploy `strip` binary does not understand newer `.relr.dyn` ELF sections. Use the project script, which disables linuxdeploy stripping:\n\n```bash\nbun run build:appimage\n```\n\nThe AppImage script also prepares the Linux Playwright sidecar executable under `src-tauri/binaries/` before invoking Tauri. Real headed web-provider login still requires a working local Node/Playwright runtime. For local sidecar launch validation:\n\n```bash\nbunx playwright install chromium\nbun run test:sidecar-launch\n```\n\n## The desktop app\n\nPickGauge ships a full Tauri 2 + Svelte 5 GUI in the Pickforge \"one ember on a cold canvas\" design system:\n\n- **Dashboard** — half-arc gauges per service with confidence, source, and freshness labels, plus local activity stats and a 14-day token chart.\n- **History** — local Codex and Claude Code usage grouped by **days, weeks, or months** (scanned from local activity files, up to a year back), with per-period totals and a gauge trail of the lowest remaining percentage per day (stored in a local SQLite history at `~/.local/share/com.pickforge.pickgauge/history.db`).\n- **Floating button** — a draggable always-on-top capsule with live mini-gauges. Click it to open the app, right-click to refresh. It never takes keyboard focus. On Wayland the app runs under XWayland so always-on-top works (set `PICKGAUGE_NATIVE_WAYLAND=1` to opt out).\n- **Sounds, not notifications** — short synthesized chimes when a gauge crosses below the low-usage threshold and when it recovers (toggle in Settings). PickGauge never posts desktop notifications.\n- **Settings** — services, providers, refresh rhythm, quota calibration, browser profiles, autostart, sounds, and the floating button, all persisted locally.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/branding/pickgauge-dashboard-mock.svg\" alt=\"PICKGAUGE · DASHBOARD — half-arc gauges with confidence labels, 14-day history, floating button, and the privacy boundary\" width=\"900\"\u003e\n\u003c/p\u003e\n\n## What it will do\n\n- Show Codex and Claude Code usage from a KDE/Linux system tray icon.\n- Alternate the tray gauge between services on a configurable interval.\n- Open a compact popup with remaining percentage, source, confidence, and last update time.\n- Persist basic provider/service settings locally.\n- Combine local CLI usage estimates with optional official-page readings.\n- Clearly label data as `high`, `medium`, `low`, or `unknown` confidence.\n- Fail gracefully when local files are missing, login expires, MFA appears, or official pages change.\n\nPlanned services:\n\n| Service | Source | Confidence |\n| --- | --- | --- |\n| Codex | Local CLI/session data and optional official analytics page | Low to high |\n| Claude Code | Local JSONL/status data and optional official usage page | Low to high |\n\nOfficial usage pages:\n\n- Codex: \u003chttps://chatgpt.com/codex/cloud/settings/analytics\u003e\n- Claude Code: \u003chttps://claude.ai/new#settings/usage\u003e\n\n## Security / Privacy\n\nPickGauge reads how much quota you have left without ever holding your account.\n\n- **No passwords, ever.** PickGauge never asks for, sees, or stores provider passwords. For its default readings it reuses the OAuth tokens the Codex and Claude Code CLIs already wrote to disk (`~/.codex/auth.json`, `~/.claude/.credentials.json`).\n- **Tokens stay in memory.** Tokens are read at refresh time, used to call the provider's own usage endpoint, refreshed in memory when they expire, and never copied into PickGauge's config, cache, logs, or local history.\n- **What leaves the machine, and only this.** To compute real remaining quota, PickGauge calls the same official endpoints the CLIs use — `chatgpt.com/backend-api/codex/usage` and `api.anthropic.com/api/oauth/usage`, plus the providers' OAuth refresh endpoints. No telemetry, no analytics, no third parties.\n- **Web reads are opt-in and isolated.** Browser-based reading of the official usage pages is disabled by default. When enabled, it runs only in dedicated, app-owned browser profiles (under `com.pickforge.pickgauge`) that you log into yourself — never your personal browser, never a shared cookie jar.\n- **Data minimization.** No raw page HTML, auth headers, cookies, tokens, or account identifiers are written to PickGauge logs, fixtures, or its local SQLite history — only computed percentages, confidence, source, and timestamps.\n- **Honest confidence.** Every reading is labeled official, estimated, merged, stale, or unavailable, so you always know how much to trust the number.\n\n## Architecture\n\n```text\nTray controller\n├─ Dynamic gauge icon\n├─ Compact popup\n└─ Settings actions\n\nUsage engine\n├─ Codex local provider\n├─ Claude local provider\n├─ Optional Codex web provider\n├─ Optional Claude web provider\n└─ Merger and confidence model\n\nPrivacy boundary\n├─ Dedicated browser profiles\n├─ Sanitized provider results\n└─ Guarded cache/session cleanup\n```\n\nStack: **Rust** for the backend, usage engine, tray control, config, and provider logic; **Tauri v2** for the lightweight desktop shell and tray integration; **Svelte** for the popup and settings UI; **KDE/Wayland first**, with CachyOS Linux as the target validation environment.\n\nPickGauge needs a real desktop shell: a persistent tray icon, native windows, local filesystem access for CLI usage data, isolated browser/session handling, and packaged installers. Tauri gives the app a Rust backend for the privacy-sensitive work while keeping the popup/settings UI lightweight with Svelte instead of shipping a full Electron runtime.\n\n## Branding\n\nBrand assets live in `assets/branding/`. The app uses the Pickforge Studio v2 dark/ember system:\n\n- `logo-mark.svg` and `logo-lockup-on-dark.svg` in the popup UI.\n- `brand-pattern.svg` and `hero-art.png` for the app surface.\n- `app-icon.svg` for generated Tauri app icons.\n- `tray-codex-64.png`, `tray-claude-64.png`, `tray-low-64.png`, and `tray-unknown-64.png` for tray states.\n\nAfter changing the source app icon, regenerate platform icons with:\n\n```bash\nbun run tauri icon assets/branding/app-icon.svg\n```\n\n## Roadmap\n\n1. Bootstrap the Tauri + Svelte app shell.\n2. Validate KDE/Wayland tray and popup behavior.\n3. Render alternating branded Codex/Claude tray icons.\n4. Add persistent settings and provider toggles.\n5. Build local usage providers.\n6. Spike browser automation for official-page reads.\n7. Add opt-in web providers with isolated sessions.\n8. Merge official baselines with local usage deltas.\n9. Packaged releases exist for Linux, Windows, and macOS; validate the macOS and Windows builds on native hosts.\n\nProject documents: [`docs/plans/pickgauge-implementation-plan.md`](docs/plans/pickgauge-implementation-plan.md) — consolidated product spec, implementation plan, validation gates, and security checklist.\n\n## Development\n\n```bash\nbun install              # install dependencies\nbun run dev              # Vite dev server on 127.0.0.1:1420\nbun run build            # build the Svelte front-end\nbun run build:appimage   # bundle the Linux AppImage (prepares the Playwright sidecar)\nbun run test             # unit tests, sidecar node tests, and sidecar package checks\nbun run lint             # ESLint over src, scripts, and sidecars\nbun run check            # svelte-check type checking\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pickforge.dev\"\u003e\n    \u003cimg src=\"assets/branding/pickforge-studio-footer.svg\" alt=\"Pickforge Studio — local-first, open source, built for people who ship\" width=\"560\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpickforge%2Fpickgauge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpickforge%2Fpickgauge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpickforge%2Fpickgauge/lists"}