{"id":49098325,"url":"https://github.com/merely04/ai-gauge","last_synced_at":"2026-04-28T09:05:29.044Z","repository":{"id":351638901,"uuid":"1207272878","full_name":"merely04/ai-gauge","owner":"merely04","description":"Real-time AI coding assistant usage monitor for Waybar — Claude Code, OpenCode, rate limits, alerts, StreamDock plugin","archived":false,"fork":false,"pushed_at":"2026-04-20T19:23:23.000Z","size":8342,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-20T22:03:04.695Z","etag":null,"topics":["ai-gauge","ai-monitoring","anthropic","claude","claude-code","developer-tools","hyprland","linux","monitoring","opencode","status-bar","stream-deck","sway","usage-tracking","waybar","waybar-module","wayland"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/merely04.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-10T19:02:47.000Z","updated_at":"2026-04-20T19:23:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/merely04/ai-gauge","commit_stats":null,"previous_names":["merely04/ai-gauge"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/merely04/ai-gauge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merely04%2Fai-gauge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merely04%2Fai-gauge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merely04%2Fai-gauge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merely04%2Fai-gauge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/merely04","download_url":"https://codeload.github.com/merely04/ai-gauge/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merely04%2Fai-gauge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32373544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"online","status_checked_at":"2026-04-28T02:00:07.250Z","response_time":56,"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-gauge","ai-monitoring","anthropic","claude","claude-code","developer-tools","hyprland","linux","monitoring","opencode","status-bar","stream-deck","sway","usage-tracking","waybar","waybar-module","wayland"],"created_at":"2026-04-20T22:00:45.756Z","updated_at":"2026-04-28T09:05:29.029Z","avatar_url":"https://github.com/merely04.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"assets/icon.png\" width=\"128\" alt=\"AI Gauge\" /\u003e\u003cbr\u003e\n  AI Gauge\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Real-time usage monitor for Claude Code, OpenCode and OpenAI Codex. Tracks rate limits with countdown timers and desktop notifications.\u003cbr\u003e\n  Runs on Linux (Waybar) and macOS (native menubar app).\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/ai-gauge\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/ai-gauge.svg?color=cb3837\u0026logo=npm\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/merely04/ai-gauge/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"MIT License\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey\" alt=\"Platform: macOS | Linux\" /\u003e\n  \u003ca href=\"https://bun.sh\"\u003e\u003cimg src=\"https://img.shields.io/badge/runtime-Bun-fbf0df?logo=bun\u0026logoColor=black\" alt=\"Runtime: Bun\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/merely04/ai-gauge/actions/workflows/publish.yml\"\u003e\u003cimg src=\"https://github.com/merely04/ai-gauge/actions/workflows/publish.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/merely04/ai-gauge/discussions\"\u003e\u003cimg src=\"https://img.shields.io/github/discussions/merely04/ai-gauge?logo=github\u0026label=discussions\" alt=\"Discussions\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n```\n✦ 44% 2h31m · 15%w\n```\n\n## Features\n\n- **Waybar module** (Linux) — live 5-hour %, weekly %, reset countdown in your status bar\n- **Native menubar app** (macOS) — Swift MenuBarExtra, same data in your menu bar\n- **Desktop notifications** — alert at 80% usage, auto-clear below 50%\n- **Right-click menu** — refresh, copy stats, change plan / token source with checkmarks (macOS), open settings\n- **StreamDock plugin** — usage stats on a physical key (Fifine AmpliGame D6)\n- **Multiple token sources** — Claude Code CLI, OpenCode, or OpenAI Codex CLI\n- **OpenCode tri-mode** — when OpenCode has Anthropic, OpenAI, and/or GitHub Copilot OAuth logins, the tooltip shows all three providers' usage side-by-side in a single view\n- **Codex JSONL fallback** — if `chatgpt.com/wham/usage` is unreachable, parses `~/.codex/sessions/*.jsonl` for the latest rate-limit snapshot\n- **WebSocket architecture** — one server broadcasts to all clients in real time\n- **systemd / launchd service** — starts on login, auto-restarts on failure\n- **Zero dependencies** — runs on Bun, no npm packages\n\n## Why ai-gauge?\n\nA few other tools do similar things. Which one fits depends on what you actually need, so here's an honest side-by-side.\n\n| Feature | ai-gauge | [waybar-ai-usage] | [ai-quota-waybar] | [ClaudeBar] |\n|---|---|---|---|---|\n| Native macOS menubar app | ✅ Swift MenuBarExtra | — | — | — |\n| Linux Waybar module | ✅ | ✅ | ✅ | ✅ |\n| Real-time WebSocket push | ✅ (60s poll, instant broadcast) | — polling | — polling | — polling |\n| Supported providers | 6 real + 2 stubs | 4 | 3 | 2 |\n| GitHub Copilot support | ✅ | ✅ | — | — |\n| Gemini CLI support | — | — | ✅ | — |\n| Browser cookie auth (no API keys) | — | ✅ Chrome/Firefox | — | — |\n| StreamDock physical-key plugin | ✅ Fifine D6 | — | — | — |\n| Claude + Codex + Copilot side-by-side view | ✅ OpenCode tri-mode | — | — | — |\n| Auto-update system | ✅ npm registry | — | — | — |\n| Zero npm runtime dependencies | ✅ | — (browser_cookie3) | ✅ pure Bash | — |\n| Stack | Bun JS + Swift | Python | Bash + jq | TypeScript + Bun |\n\n[waybar-ai-usage]: https://github.com/NihilDigit/waybar-ai-usage\n[ai-quota-waybar]: https://github.com/komagata/ai-quota-waybar\n[ClaudeBar]: https://github.com/andresreibel/ClaudeBar\n\n### Where ai-gauge is unique\n\n- The only tool with a native macOS menubar app (Swift, no Electron, no browser window)\n- Multi-provider unified view: Claude and Codex usage in a single tooltip when using OpenCode\n- StreamDock plugin for physical hardware key display\n- Provider registry covers Z.ai, MiniMax, OpenRouter, Komilion and others beyond the big two\n\n### Where competitors are stronger\n\n- **NihilDigit/waybar-ai-usage** is the right pick if you want browser-cookie auth (no credential files to manage, works with Chrome/Firefox sessions out of the box)\n- **komagata/ai-quota-waybar** is the right pick if you use Gemini CLI and want a zero-dependency pure Bash solution with no Bun requirement\n- **andresreibel/ClaudeBar** has a clean click-to-toggle UX between Claude and Codex and handles 429 backoff gracefully with cached payloads\n\n## LLM Agent Install\n\n```\nRead and follow the installation guide:\nhttps://raw.githubusercontent.com/merely04/ai-gauge/master/docs/LLM_INSTALL.md\n```\n\n## Install\n\n```bash\nbun add -g ai-gauge\nai-gauge setup\n```\n\nTo uninstall:\n\n```bash\nai-gauge uninstall\nbun remove -g ai-gauge\n```\n\n**Linux**: requires [Bun](https://bun.sh) and a desktop with Waybar (Hyprland, Sway, or any wlroots compositor).\n\n**macOS**: requires [Bun](https://bun.sh) and macOS 13+. `ai-gauge setup` installs a native Swift menubar app and a launchd LaunchAgent instead of Waybar and systemd.\n\n\u003e **Note**: GitHub Releases do not ship a standalone `.app` download. The macOS menubar app is a UI client only — it requires the `ai-gauge-server` daemon which lives inside the npm package and is configured by `ai-gauge setup`. Always install via `bun add -g ai-gauge`.\n\n### macOS Gatekeeper — if the menubar icon doesn't appear\n\nThe `.app` bundle is **ad-hoc signed** (not notarized with an Apple Developer ID). `ai-gauge setup` automatically runs `xattr -dr com.apple.quarantine` to let macOS launch it, but a few edge cases may still trigger \"cannot verify developer\":\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFix: one-liner that handles most cases\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nxattr -dr com.apple.quarantine \"$(bun pm -g bin)/../lib/node_modules/ai-gauge/bin/AIGauge.app\"\nlaunchctl bootout gui/$(id -u)/com.ai-gauge.menubar 2\u003e/dev/null\nlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.ai-gauge.menubar.plist\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eStill blocked? → System Settings → Privacy \u0026 Security\u003c/strong\u003e\u003c/summary\u003e\n\n1. Open **System Settings → Privacy \u0026 Security**\n2. Scroll to the bottom — if you see a `\"AIGauge\" was blocked…` notice, click **Allow Anyway**\n3. Reload the menubar agent (one-liner above)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCheck if quarantine is still set\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nxattr -l \"$(bun pm -g bin)/../lib/node_modules/ai-gauge/bin/AIGauge.app/Contents/MacOS/AIGauge\"\n```\n\nIf you see `com.apple.quarantine` in the output, the flag is still present — run the fix above.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEdge cases (rare)\u003c/strong\u003e\u003c/summary\u003e\n\n- **Lockdown Mode** (System Settings → Privacy \u0026 Security → Lockdown Mode): ad-hoc signed apps are refused. Disable Lockdown Mode to use ai-gauge, or use only notarized software.\n- **\"Allow applications downloaded from: App Store only\"**: change to **App Store and identified developers** in System Settings → Privacy \u0026 Security.\n- **MDM / corporate device**: your admin may block unsigned binaries. Ask them to whitelist `com.ai-gauge.menubar`, or install a local build from source.\n\n\u003c/details\u003e\n\n## What it shows\n\n**Bar**: `✦ \u003c5h%\u003e \u003ccountdown\u003e · \u003cweekly%\u003ew`\n\n![bar](assets/bar.png)\n\n**Tooltip** (hover):\n\n```\nClaude Code Usage\n───────────────\n5-hour:  44%  (resets in 2h 31m)\nWeekly:  15%  (resets in 6d 17h 54m)\nSonnet:  0%\n───────────────\nExtra: $171.22/$200 (86%)\n```\n\nWhen `tokenSource: opencode` and your OpenCode auth file carries any combination of Anthropic, OpenAI, and GitHub Copilot OAuth logins, the tooltip shows all of them side-by-side in a single view:\n\n![multi-provider tooltip](assets/macos-multi-provider.png)\n\n```\nClaude\n───────────────\n5-hour:  31%  (resets in 2h 29m)\nWeekly:  16%  (resets in 2d 9h 59m)\nSonnet:   2%  (resets in 2d 9h 59m)\n───────────────\nExtra: $204.10/$200 (100%)\n───────────────\nCodex\n5-hour:  24%  (resets in 4h 12m)\nWeekly:  15%  (resets in 3d 11h 44m)\n───────────────\nGitHub Copilot\nPlan:    pro\nPremium: 50%  (150/300)\nResets:  in 3d 12h\n```\n\nOpenCode logs into Copilot via Device Flow OAuth (`opencode auth login github-copilot`), storing the `gho_*` token in `~/.local/share/opencode/auth.json`. ai-gauge picks it up automatically — no extra configuration needed when `tokenSource: opencode`.\n\nThe current plan and token source are reflected as **checkmarks in the submenu** (macOS) and in the Linux tooltip footer.\n\n![tooltip](assets/tooltip.png)\n\n**States**:\n\n| State | Color | Condition |\n|-------|-------|-----------|\n| normal | system text color | \u003c 50% |\n| warning | yellow | 50-79% |\n| critical | red | \u003e= 80% (sends desktop notification once) |\n| waiting | very dim | Connecting to server (starting up or server down) |\n\n## macOS — Native Menu Bar\n\nSame data, native Mac UI. Lives in the menu bar (no Dock icon thanks to `LSUIElement`).\n\n**In the menu bar:**\n\n![macOS menu bar](assets/macos-menubar.png)\n\n**Click to open the full menu** — usage breakdown on top, actions below:\n\n![macOS menu](assets/macos-menu.png)\n\n**Submenus** show current selection with a checkmark — change plan or token source on the fly:\n\n![macOS submenu](assets/macos-submenu.png)\n\n**About panel** — standard macOS About with version, license, GitHub link:\n\n![macOS about](assets/macos-about.png)\n\n**Menu** (right-click on Linux, click on macOS):\n\n- Copy usage summary (clipboard)\n- Raw data (clipboard)\n- 🔑 Token source: \\\u003ccurrent\\\u003e ▸ (Linux: direct one-click to source selection with checkmarks)\n- 📋 Plan: \\\u003ccurrent\\\u003e ▸ (Linux: direct one-click to plan selection with checkmarks)\n- 🎨 Display mode: \\\u003ccurrent\\\u003e ▸ (inline submenu)\n- Change plan ▸ (macOS submenu — current marked with ✓)\n- Change token source ▸ (macOS submenu — current marked with ✓)\n- ⚙ Settings (advanced configuration)\n- ↻ Refresh now\n- Restart server\n- Reveal Config in Finder (macOS) / Open settings (Linux)\n- About AI Gauge (macOS — shows version, license, GitHub link)\n- Quit\n\n## Configuration\n\nConfig file: `~/.config/ai-gauge/config.json`\n\n```json\n{\"tokenSource\": \"claude-code\", \"plan\": \"max\"}\n```\n\nOn first install, `ai-gauge setup` auto-detects which token source to use by checking which credential files exist:\n\n1. **OpenCode** (`~/.local/share/opencode/auth.json` on Linux, `~/Library/Application Support/opencode/auth.json` on macOS)\n2. **OpenAI Codex** (`~/.codex/auth.json` or `$CODEX_HOME/auth.json`)\n3. **Claude Code** (Keychain on macOS, `~/.claude/.credentials.json` on Linux)\n\nIf multiple sources exist, the most recently modified one wins (with fixed priority `opencode \u003e codex \u003e claude-code` as a tiebreaker). Auto-detect runs **only on first install** — subsequent `ai-gauge setup` runs preserve your existing choice.\n\nTo switch later, use the menu (macOS submenu / Linux right-click → \"🔑 Token source\") or CLI:\n\n```bash\nai-gauge-config set tokenSource opencode\n```\n\n| Field | Values | Description |\n|-------|--------|-------------|\n| `tokenSource` | `claude-code` (default), `opencode`, `codex`, `github`, `claude-settings:\u003cname\u003e` | OAuth credential source |\n| `plan` | `max`, `pro`, `team`, `enterprise`, `unknown` (Anthropic) \u003cbr\u003e `plus`, `pro`, `business`, `enterprise`, `edu` (Codex) | Subscription plan (shown in tooltip) |\n| `displayMode` | `full` (default), `percent-only`, `bar-dots`, `number-bar`, `time-to-reset` | Display format for menubar/waybar |\n\nChange settings via menu (macOS submenu / Linux walker UI) or CLI (works on both):\n\n```bash\nai-gauge-config set tokenSource opencode\nai-gauge-config set plan max\nai-gauge-config get\n```\n\n## GitHub Copilot\n\nai-gauge can monitor your Copilot monthly premium-request quota for Individual plans (Free, Pro, Pro+).\n\n```bash\n# Works with default gh storage (Keychain on macOS, Secret Service on Linux, or --insecure-storage plaintext)\ngh auth login\nai-gauge-config set tokenSource github\nsystemctl --user restart ai-gauge-server   # Linux\n# macOS: launchctl kickstart -k gui/$(id -u)/com.ai-gauge.server\n```\n\nai-gauge calls `gh auth token --hostname github.com` at each poll, so any gh storage backend (Keychain on macOS, Secret Service on Linux, or `--insecure-storage` plaintext) works out of the box.\n\n**Headless / CI mode**: If `gh` binary is unavailable, copy a `gho_*` OAuth token (obtained via `gh auth token --hostname github.com` on a workstation) into `~/.config/ai-gauge/copilot-token` (single-line plain text file). The daemon falls back to this file when both Tier 1 (shell-out) and Tier 2 (hosts.yml plaintext) fail.\n\n\u003e **Important — PAT compatibility**: Classic Personal Access Tokens (`ghp_*`) and fine-grained PATs (`github_pat_*`) **do not work** for Copilot quota monitoring — the `/copilot_internal/v2/token` endpoint requires the OAuth token (`gho_*`) issued by `gh auth login`. ai-gauge will reject any other token format with a clear error log.\n\n**Limitations**: v1 supports Individual plans only (Free/Pro/Pro+). Business/Enterprise quotas deferred to v1.1. GitHub Enterprise Server not supported. Multi-account gh CLI uses first `github.com:` block only.\n\n\u003e Note: ai-gauge mirrors official VS Code Copilot extension headers to authenticate the internal API. If GitHub changes their internal API contract, ai-gauge may break temporarily — please file an issue.\n\n## OpenAI Codex (ChatGPT subscription)\n\nai-gauge can monitor Codex CLI usage from a ChatGPT Plus / Pro / Business / Enterprise / Edu subscription.\n\n![Codex submenu](assets/macos-codex-submenu.png)\n\n```bash\n# Make sure Codex CLI is logged in (if you haven't already):\ncodex auth login\n\n# Tell ai-gauge to read from ~/.codex/auth.json:\nai-gauge-config set tokenSource codex\n```\n\nThe daemon will fetch `https://chatgpt.com/backend-api/wham/usage` (the same endpoint Codex CLI itself uses) once a minute. The tooltip then shows 5-hour and weekly windows, plus the code-review window and credit balance when present.\n\n\u003e **Note**: `/wham/usage` is an undocumented internal endpoint. We mirror Codex CLI's headers (`Authorization: Bearer ...`, `ChatGPT-Account-Id: ...`, `User-Agent: codex_cli_rs/...`). If the endpoint changes upstream, ai-gauge falls back to parsing `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` for the latest `token_count` event so you still see something.\n\n### `codex` requirements\n\n- Codex CLI installed and logged in (`codex` will create `~/.codex/auth.json` on first login)\n- Credentials stored in **file mode** — the default. If you set `cli_auth_credentials_store: \"macOS_keychain\"` in `~/.codex/config.toml`, ai-gauge cannot read your tokens (background launchd agents can't show interactive Keychain prompts) and will degrade to JSONL session parsing.\n- Plain OpenAI API keys (`sk-...`) are **not supported** — the `/wham/usage` endpoint requires the OAuth `access_token` from `codex auth login`.\n\n## Using a Different Claude Provider\n\nYou can monitor usage from alternative Claude API providers by creating a settings file in `~/.claude/`:\n\n```bash\n# Create a settings file for your provider\ncat \u003e ~/.claude/settings.myprovider.json \u003c\u003c 'EOF'\n{\n  \"env\": {\n    \"ANTHROPIC_BASE_URL\": \"https://api.yourprovider.com/anthropic\",\n    \"ANTHROPIC_AUTH_TOKEN\": \"your-token-here\"\n  }\n}\nEOF\n\n# Set it as your token source\nai-gauge-config set tokenSource claude-settings:myprovider\n```\n\nThen restart the server: `systemctl --user restart ai-gauge-server` (Linux) or `launchctl kickstart -k gui/$(id -u)/com.ai-gauge.server` (macOS).\n\n### Supported Providers\n\n| Provider | `ANTHROPIC_BASE_URL` | Auth | Balance |\n|----------|---------------------|------|---------|\n| Z.ai | `https://api.z.ai/api/anthropic` | Token (no Bearer) | Rate limits |\n| MiniMax | `https://api.minimax.io/api/anthropic` | Bearer token | Rate limits |\n| OpenRouter | _(fixed URL)_ | Bearer token | Credit balance |\n| Komilion | _(fixed URL)_ | Bearer token | Wallet balance |\n| Packy | _(no public API)_ | — | — |\n\n### Notes\n\n- **Anthropic API keys** (`sk-ant-*`) cannot fetch usage via this tool. The usage endpoint requires OAuth tokens (from Claude Code CLI or OpenCode). Settings files with a plain Anthropic API key will show the source as `unknown` with no quota data.\n- **Packy** has no public balance API. Selecting it will show the provider name but no usage data.\n- File names must match `[a-zA-Z0-9_][a-zA-Z0-9_.-]*` (e.g. `settings.z.json`, `settings.mywork.json`).\n- `settings.local.json` is excluded from discovery (reserved for local overrides).\n\n## Update Notifications\n\nai-gauge automatically checks for updates every 24 hours (with a 30-second initial delay after startup) and notifies you via the menubar/waybar.\n\n### What you'll see\n\n**macOS**: An orange dot appears in the menu bar icon. Click to open the menu — an \"Update to vX.Y.Z\" item appears at the top. Click it to update. You'll also get a native notification.\n\n**Linux (Waybar)**: The waybar text gains a ⬆ suffix and turns yellow (`update-available` CSS class). Use the right-click menu → \"✨ Update to vX.Y.Z\" to trigger the update.\n\nIf the automatic update fails (e.g., due to permissions), the install command is copied to your clipboard.\n\n### Manual check\n\n- **macOS**: Menu → \"Check for updates now\"\n- **Linux**: Right-click menu → \"🔍 Check for updates\"\n- **CLI**: `echo '{\"type\":\"checkUpdate\"}' | bun lib/send-ws.js`\n\n### Disable update checks\n\n**Permanently** (per-machine):\n```bash\nai-gauge-config set autoCheckUpdates false\n```\n\n**Session**: Set `NO_UPDATE_NOTIFIER=1` in the environment before starting the daemon.\n\n**CI environments**: Update checks are automatically skipped when any of these env vars are set: `CI`, `CONTINUOUS_INTEGRATION`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `JENKINS_HOME`, `BUILDKITE`, `DRONE`, `TRAVIS`.\n\n**Testing / development env vars** (not for production use):\n\n| Variable | Effect |\n|----------|--------|\n| `AIGAUGE_DETECT_SKIP_KEYCHAIN=1` | Skip macOS Keychain during auto-detect (useful in headless/SSH sessions) |\n| `AIGAUGE_SETUP_DRY_RUN=1` | Run setup without side effects — creates `~/.config/ai-gauge/config.json` only, skips systemctl/launchctl/waybar patching |\n| `AIGAUGE_SETUP_PLATFORM=\u003clinux\\|darwin\u003e` | Override platform detection in setup scripts (testing only) |\n\n### Dismiss a specific version\n\nTo silence a specific version without disabling checks entirely:\n\n```bash\necho '{\"type\":\"dismissUpdate\",\"version\":\"2.0.0\"}' | bun lib/send-ws.js\n```\n\nThe notification is suppressed until a newer version appears or you run:\n\n```bash\necho '{\"type\":\"undismissUpdate\"}' | bun lib/send-ws.js\n```\n\n### Running without a service manager (Docker, minimal Linux)\n\nai-gauge is designed around systemd (Linux) and launchd (macOS). After a successful update, the daemon calls `process.exit(0)` and relies on the service manager to restart it.\n\nIf you run the daemon in an environment without a service manager — e.g. a Docker container, `tmux` session, or PID 1 of a minimal Linux install — the process will terminate on update and **not** come back automatically. Either:\n\n- Disable auto-update: `ai-gauge-config set autoCheckUpdates false`\n- Wrap the daemon in your own restart loop (supervisord, runit, `while true; do ai-gauge-server; sleep 1; done`)\n\nThe update still works in the sense that the new version is installed via `npm`/`bun`/`pnpm`, but the running process is not replaced until you manually start it again.\n\n## StreamDock (Fifine D6)\n\nThe plugin shows usage stats on a physical key of the Fifine AmpliGame D6 stream controller.\n\n![deck](assets/deck.jpg)\n\n**Requirements**: Fifine D6 + StreamDock app running via Wine on Linux.\n\n**Setup**: `ai-gauge setup` copies the plugin automatically. Open StreamDock → find **AI Gauge** in the action list → drag it onto a key.\n\nThe button connects to `ai-gauge-server` via WebSocket and updates in real time. If the server is not running, the button shows `--`.\n\n## How it works\n\n`ai-gauge-server` runs as a background daemon (systemd on Linux, launchd on macOS) and polls the relevant provider's usage API every 60 seconds:\n\n- **Claude Code / OpenCode (Anthropic OAuth)** → `https://api.anthropic.com/api/oauth/usage`\n- **OpenAI Codex** → `https://chatgpt.com/backend-api/wham/usage` (with JSONL fallback to `~/.codex/sessions/`)\n- **OpenCode tri-mode** → all available endpoints fetched in parallel; broadcast carries a top-level `secondary` field for Codex/OpenAI and a top-level `copilot` field for GitHub Copilot, when those OAuth blocks are present in the OpenCode auth file\n- **GitHub Copilot** → `https://api.github.com/copilot_internal/v2/token` (authenticated via `gh auth token` shell-out → fallback to `~/.config/gh/hosts.yml` → fallback to `~/.config/ai-gauge/copilot-token`)\n- **Custom `claude-settings:*` providers** → whatever `ANTHROPIC_BASE_URL` you configure (Z.ai, MiniMax, OpenRouter, Komilion, Packy)\n\nResults are broadcast to all connected WebSocket clients on `ws://localhost:19876`.\n\nOn **Linux**, `ai-gauge-waybar` is a thin WebSocket client that renders each update as waybar-compatible JSON. On disconnect it shows a waiting state and reconnects automatically.\n\nOn **macOS**, `bin/ai-gauge-menubar` is a native Swift app using MenuBarExtra. It connects to the same WebSocket server and shows usage in the system menu bar.\n\nThe server writes `usage.json` atomically to `$XDG_RUNTIME_DIR/ai-gauge/` on Linux or `$TMPDIR/ai-gauge/` on macOS, so other tools can read it too.\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `bin/ai-gauge` | Main CLI — setup, uninstall, status |\n| `bin/ai-gauge-server` | WebSocket server — fetches Anthropic API, broadcasts to clients (port 19876) |\n| `bin/ai-gauge-waybar` | Thin WS client — renders waybar JSON from server data (Linux) |\n| `bin/ai-gauge-menubar` | Native Swift menubar app binary — universal arm64+x86_64 (macOS) |\n| `bin/ai-gauge-menu` | Click menu — refresh, copy, settings |\n| `bin/ai-gauge-config` | Settings CLI/UI — token source, plan name |\n| `lib/ai-gauge-server.service` | systemd user service unit template (Linux) |\n| `lib/ai-gauge-server.plist.template` | launchd LaunchAgent plist template (macOS) |\n| `lib/ai-gauge-menubar.plist.template` | launchd plist for the menubar app (macOS) |\n| `bin/AIGauge.app/` | Pre-built macOS app bundle (universal arm64+x86_64, ad-hoc signed) |\n| `macos/AIGauge/` | Swift source for the native menubar app (SPM project) |\n| `scripts/build-macos-binary.sh` | Reproducible build: `swift build` + `lipo` + `codesign --deep` + bundle wrap |\n| `scripts/generate-icon.sh` + `generate-icon.swift` | Procedural app icon renderer (Swift Core Graphics → `.icns`) |\n| `lib/notify.js` | Cross-platform notification helper (notify-send on Linux, no-op on macOS) |\n| `lib/bash-helpers.sh` | Portable `is_macos`, `resolve_path`, `sed_inplace` for bash scripts |\n| `lib/streamdock-plugin/` | StreamDock (Fifine D6) button plugin |\n\nBoth setup and uninstall are idempotent.\n\n## Community \u0026 Feedback\n\nai-gauge is early — first users still arriving. Feedback at any level helps:\n\n- **Questions, install issues, \"how do I do X\"** → [Discussions / Q\u0026A](https://github.com/merely04/ai-gauge/discussions/categories/q-a)\n- **Feature ideas, brainstorming** → [Discussions / Ideas](https://github.com/merely04/ai-gauge/discussions/categories/ideas)\n- **Confirmed bugs with repro steps** → [Open an Issue](https://github.com/merely04/ai-gauge/issues/new?template=bug_report.yml)\n- **Request a new AI provider** (DeepSeek, Groq, Gemini, Cursor, etc.) → [Provider Request](https://github.com/merely04/ai-gauge/issues/new?template=provider_request.yml)\n- **Show off your setup** → [Discussions / Show and tell](https://github.com/merely04/ai-gauge/discussions/categories/show-and-tell)\n\nRead the [welcome post](https://github.com/merely04/ai-gauge/discussions/3) for the full triage map.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerely04%2Fai-gauge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmerely04%2Fai-gauge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerely04%2Fai-gauge/lists"}