{"id":"provider-usage","repo":"nerveband/paseo-provider-usage","url":"https://github.com/nerveband/paseo-provider-usage","name":"provider-usage","description":"Paseo plugin that shows Claude, Codex, and Antigravity plan usage in the sidebar","categories":["monitoring","provider"],"platforms":[],"caveats":[],"images":["https://raw.githubusercontent.com/nerveband/paseo-provider-usage/f135b14f75093cc603b48d6030b27efa885e5963/docs/screenshot.png"],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":false,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-10-15T12:34:13.341Z","addedAt":"2026-09-10T18:09:18+03:00","version":"0.4.0","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-10-15T12:14:24.405Z","commit":"f135b14f75093cc603b48d6030b27efa885e5963"},"license":"MIT","paseoVersionRequirement":">=0.8.0","descriptionNodes":[{"type":"text","text":"Paseo plugin that shows Claude, Codex, and Antigravity plan usage in the sidebar"}],"caveatNodes":[],"manifest":{"id":"provider-usage","requirements":{"paseo":">=0.8.0"}},"repoMeta":{"stars":1,"defaultBranch":"main","pushedAt":"2026-09-26T14:52:57Z"},"owner":{"login":"nerveband","avatarUrl":"https://avatars.githubusercontent.com/u/1530727?v=4"},"installNotesHtml":"<p>Install directly from Git:</p>\n<pre><code class=\"language-bash\">paseo plugin add nerveband/paseo-provider-usage\npaseo plugin ls\n</code></pre>\n<p>Check and apply updates:</p>\n<pre><code class=\"language-bash\">paseo plugin status provider-usage\npaseo plugin update provider-usage\n</code></pre>\n<p>For local development, clone the repository, run <code>npm install</code> and <code>npm run typecheck</code>, then use <code>paseo plugin install \"$PWD\"</code>.</p>\n<p>Open the app and pick <strong>Usage</strong> in the sidebar, or run the <strong>Open plan usage</strong> action from the\nCommand Center (<code>Ctrl</code>/<code>Cmd</code> + <code>K</code>).</p>\n<p>After editing the source, apply it with <code>paseo plugin reload provider-usage</code>. Do not restart the\ndaemon; that stops running agents.</p>","readmeText":"# Paseo plan usage\n\nA [Paseo](https://paseo.sh) plugin that puts Claude, Codex, Antigravity, and OpenRouter usage in the\nsidebar, next to Tasks and any other sidebar contribution. One click, no menu digging, no second\nwindow.\n\n![The Usage surface showing Claude, Codex, Antigravity, and OpenRouter usage above agent activity](docs/screenshot.png)\n\nEach row is one quota window: the label, when it resets, the share consumed, and a zero-baseline\nbar. Rows at 90% or above turn red. The account line names the plan, account, and which data\nsource answered.\n\nInternal model-pool lanes such as `gpt-reserve` are hidden. Those are identifier-named\nmirrors of a real window rather than limits you plan around.\n\n## Why\n\nPaseo already knows provider usage, but it lives behind a hover tooltip and a settings screen.\nThis plugin turns the same information into a persistent, keyboard-reachable sidebar surface and\nadds Antigravity, which Paseo does not report.\n\n## Features\n\n- **Plans:** Rolling quota windows (session, weekly, monthly) for Claude, Codex, and Antigravity, with reset times. Rows at 90% or above turn red.\n- **OpenRouter:** Credit remaining, used, and added, plus 30-day activity (tokens, requests, models) as CodexBar reports them.\n- **Agent activity:** Token totals, estimated cost, and sessions for 24h, 7d, 14d, 30d, or all time; a per-day (or per-hour) bar chart you can tap to inspect; and a ranked model list. Tap a model to filter the view to it.\n\n## What it reads\n\nUsage is fetched with the [CodexBar](https://github.com/steipete/CodexBar) CLI, which reuses\ncredentials you already have instead of asking for new ones.\n\n| Provider | Source |\n| --- | --- |\n| Codex | The Codex CLI's own OAuth session. |\n| Claude | An OAuth access token borrowed from [OMP](https://paseo.sh/omp), else CodexBar's own strategies. |\n| Antigravity | The same OMP path, else CodexBar's local Antigravity probes, `agy` CLI, or Google OAuth. |\n| OpenRouter | The API key stored in CodexBar, else `OPENROUTER_API_KEY`. |\n\n### OpenRouter setup\n\n```bash\ncodexbar config set-api-key --provider openrouter --stdin   # paste the key, then Ctrl-D\n```\n\nA regular API key shows credits and that key's own spend. A Management API key also shows\naccount-wide 30-day activity. CodexBar reports model counts but not spend per model, so the\nplugin does not show per-model OpenRouter spend.\n\nNothing launches a GUI. Antigravity usage is read over Google's OAuth quota endpoints, so neither\nthe Antigravity desktop app nor an interactive `agy` session has to be running.\n\nIf OMP is not installed, the Claude and Antigravity rows fall back to CodexBar's own provider\nstrategies (`--source auto`) rather than failing, so the plugin is still useful on a machine that\nauthenticates those providers another way.\n\n## Requirements\n\n- A Paseo daemon with plugins enabled.\n- The CodexBar CLI (`codexbar`) on `PATH` or in `~/.local/bin`, or `CODEXBAR_BIN` pointing at it.\n  Linux and macOS builds are published on\n  [CodexBar releases](https://github.com/steipete/CodexBar/releases).\n- Optional: OMP with `anthropic` and `google-antigravity` accounts signed in, for the\n  token-bridged Claude and Antigravity paths.\n\n## Install\n\nInstall directly from Git:\n\n```bash\npaseo plugin add nerveband/paseo-provider-usage\npaseo plugin ls\n```\n\nCheck and apply updates:\n\n```bash\npaseo plugin status provider-usage\npaseo plugin update provider-usage\n```\n\nFor local development, clone the repository, run `npm install` and `npm run typecheck`, then use `paseo plugin install \"$PWD\"`.\n\nOpen the app and pick **Usage** in the sidebar, or run the **Open plan usage** action from the\nCommand Center (`Ctrl`/`Cmd` + `K`).\n\nAfter editing the source, apply it with `paseo plugin reload provider-usage`. Do not restart the\ndaemon; that stops running agents.\n\n## Configuration\n\n| Variable | Effect |\n| --- | --- |\n| `CODEXBAR_BIN` | Absolute path to the CodexBar CLI. Defaults to the first `codexbar` found on `PATH`, `~/.local/bin`, `/opt/homebrew/bin`, or `/usr/local/bin`. |\n\nProviders, refresh cadence, and thresholds are code-level constants in `usage.server.ts` and\n`main.client.tsx`.\n\n## Refresh behavior\n\nOpening the surface never blocks on a fetch. The daemon answers with the last snapshot it has\nand revalidates behind it, so you read numbers immediately and see `Updating…` next to the\ntimestamp while fresh ones arrive. A spinner appears only on the very first run, when there is\nno snapshot yet.\n\nThe snapshot is written to `$XDG_STATE_HOME/paseo-provider-usage/snapshot.json` (default\n`~/.local/state/...`) with mode `0600`, so a daemon or plugin reload still paints instantly. It\nholds usage numbers, reset times, and the account label — never a token.\n\nProvider quota endpoints are rate limited per account, so fetching stays deliberately quiet:\n\n- A snapshot under 60 seconds old is served as-is, with no upstream fetch.\n- An older snapshot is served immediately and refreshed in the background.\n- Concurrent requests share one in-flight fetch.\n- The surface revalidates every five minutes, and polls every two seconds only while a\n  background refresh is outstanding.\n- **Refresh** bypasses the cache and waits for fresh numbers.\n\nClaude's OAuth token is read from OMP's cache first. A forced token refresh mints a new access\ntoken and invalidates the previous one, so it is used only after the provider rejects the cached\ntoken.\n\n## Security\n\n- Backend plugin code is trusted and unsandboxed; it runs beside your Paseo daemon.\n- Tokens are passed to CodexBar through a `0600` config file in a private temporary directory\n  that is deleted after each fetch.\n- Tokens are never logged, printed, or written into this repository.\n- A failing provider degrades to a message on its own row; the other providers keep rendering.\n\n## Development\n\n```bash\nnpm run typecheck                      # required before install or reload\npaseo plugin reload provider-usage     # apply source edits\npaseo plugin logs provider-usage       # backend stdout/stderr\n```\n\n| File | Role |\n| --- | --- |\n| `index.ts` | Registers the RPC handler, surface, sidebar item, and Command Center action. |\n| `usage.shared.ts` | Zod contract shared by both runtimes. |\n| `usage.server.ts` | Token bridge, CodexBar invocation, normalization, caching. |\n| `main.client.tsx` | The React Native surface. |\n\nVerified on Linux (`x86_64`) against Paseo daemon 0.5.2 and CodexBar 0.55.1, in light and dark\nthemes at desktop and compact widths.\n\n## Credits\n\nUsage data comes from [CodexBar](https://github.com/steipete/CodexBar) by Peter Steinberger.\n\n## License\n\n[MIT](LICENSE)\n"}