clawmeter

README

Clawmeter

Clawmeter is a system tray and CLI quota meter for AI coding tools.

It answers the questions that matter while you are working: am I on track, what is most likely to run out, and when does it reset?

Install

macOS:

brew install tnunamak/clawmeter/clawmeter
brew services start clawmeter

Linux:

curl -fsSL https://raw.githubusercontent.com/tnunamak/clawmeter/main/install.sh | sh -s -- --start

Windows:

Download ClawmeterSetup.exe from the latest release, verify it with SHA256SUMS.txt, then run the installer. It creates a Start Menu tray shortcut, adds clawmeter to your user PATH, and includes an uninstall entry.

Windows artifacts are currently unsigned. The future signing path is documented in the Code signing policy and SignPath readiness checklist.

clawmeter providers

WinGet will install that same setup exe once the package is accepted:

winget install --id tnunamak.Clawmeter -e

Advanced/manual fallback: download clawmeter-windows-amd64.exe from the same release if you only want the portable binary.

.\clawmeter-windows-amd64.exe providers

You can also download .deb, .rpm, macOS, Linux, and Windows binaries from the latest release.

Then run:

clawmeter setup --all
clawmeter doctor

Setup installs the mainstream local surface Clawmeter can verify today: a Claude Code statusline. Every agent can also pull the same cheap quota summary with clawmeter status --agent.

Why Use It

• See your riskiest quota without opening provider dashboards.
• Compare current usage with expected pace for the reset window.
• See reset credits and their earliest expiry under the matching provider source.
• Cycle the tray icon between concrete provider/quota windows.
• Reuse existing credentials without rewriting them. When required, Clawmeter refreshes short-lived access tokens only against the provider's own OAuth service.

Claude Web Reset Grants

Claude's Usage page can show promotional reset grants that Claude Code's local usage data does not include. To read them, choose Check Claude resets in the tray. A local Clawmeter page opens with the steps: save the Clawmeter bookmark (first time only), open Claude Usage, and click the bookmark there. The page shows the result when it arrives.

Clawmeter files the result under the Claude source signed in to the same organization as the browser, so there is nothing to confirm. The bookmark sends a salted hash of the organization ID, never the ID itself, plus each grant's remaining count, start, expiry, and paused state. Only grants usable now count. Clawmeter stores no cookies, organization IDs, or raw responses. If you later sign that source in to a different organization, the saved result is dropped.

The result shows under its Claude source as Resets: 1 · expires Oct 22 · checked Oct 7. It is a snapshot, not a live poll: check again after you use a reset. Your browser may ask to let claude.ai access your local network; allow it. clawmeter claude-web-bookmarklet prints the bookmark URL.

Claude API Credits

Prepaid Claude API credits (for example the monthly API credit a Max plan grants) have no API for their balance or expiry, and Anthropic's Usage & Cost Admin API is unavailable to individual accounts. Clawmeter reads them from the Claude Console with the same bookmark: choose Check API credits in the tray, open the Claude Console, and click the bookmark there.

When a Claude plan funds the organization (the Console links it to that plan's claude.ai organization), the pool shows on the Claude source signed in to that plan:

Claude · Default: 5h: 1% … · API credits: $199.88 left · spent $0.11 this month · on pace to spend $1.84 more before it expires Oct 24 19:00 · checked 12:53

Other Console organizations show as their own pools under Claude API. The bookmark proves the plan link with a salted hash of the plan's organization ID, as reset checks do, and the pool moves back under Claude API if that source signs in elsewhere.

The balance is what the Console's billing page shows: purchased plus promotional credit. Spend this month is the Console's own total. The pace is the average daily cost from the Console's cost report over up to 7 days (at least one day), and the projection extends it to the next credit expiry, or to when the balance runs out first. Expiry shows in local time; the Console shows UTC dates. The bookmark refuses to send data when the Console's daily costs and its month total disagree. clawmeter status --agent lists every pool under api_credits=[...] with exact amounts so agents can budget API spend.

The bookmark sends a hash of the organization ID, never the ID, and Clawmeter stores no cookies. Like resets, a pool is a snapshot: check again after heavy API use.

Read The Icon

The provider logo stays in the circular center chip. The text names the quota window: 5H, 7D, 7A, 7S, or MO.

The radial meter compares actual burn with expected pace. Gray shows the shared baseline; a solid green segment means you are under pace, and a solid red segment means you are over pace.

• Left-click the tray icon to cycle through active provider/quota windows.
• Double-click the tray icon to return to Auto.
• Auto picks a quota window and is not part of the left-click cycle.
• The tray menu can switch Auto between Risk, EST, and Runway:
  • Risk: the quota projected to block you soonest.
  • EST: the highest projected-at-reset percentage.
  • Runway: the quota with the most projected room left.
• Right-click for details, refresh, update, and launch-at-login.
• A small blue dot on the tray icon means an update is available.
• Use Refresh Now when you want an immediate quota/update check.

CLI

clawmeter

PROVIDER   WINDOW    USAGE                 PCT  resets IN      PACE
Claude     5h        ██░░░░░░░░░░░░░░░░░░  11%  resets 4h00m   est. 55% at reset
           7d All    ██████████████████░░  89%  resets 1d10h   est. 112% at reset · runs out in 16h
           7d Sonnet ░░░░░░░░░░░░░░░░░░░░   2%  resets 4d23h   est. 7% at reset

Useful commands:

clawmeter providers      # detected providers and auth status
clawmeter providers diagnose codex --pretty  # privacy-safe live diagnostic
clawmeter providers diagnose claude --raw     # raw provider response per source (redacted), to verify a reading
clawmeter providers source list               # enrolled source ids and labels
clawmeter providers source add <provider> <id> <kind> [ref] [--label <label>]
clawmeter providers source remove claude work # final removal also disables the provider
clawmeter claude         # one provider
clawmeter codex          # Codex quota
clawmeter grok           # Grok quota
clawmeter --json         # machine-readable output
clawmeter statusline     # compact Claude/statusline segment

Restart a running tray after changing sources to apply the change.

Source enrollment uses provider-declared kinds. Run clawmeter providers source help <provider> to see the exact routes that provider supports. native takes no ref; file and directory routes require absolute paths; environment routes take the variable name, never its secret value. Unsupported kinds fail before configuration is saved.

When the currently detected native source exists, adding the first named source keeps it as Default. Otherwise Clawmeter adds only the named source, avoiding a broken empty row. Every named source uses only its enrolled credential route. Clawmeter does not scan for additional accounts or combine quotas across sources.

clawmeter providers source help codex
clawmeter providers source add codex work codex-home ~/.codex-work --label Work

clawmeter status --agent # token-efficient all-quota summary for AI agents
clawmeter setup --all    # install mainstream local integrations
clawmeter doctor         # provider and integration readiness
clawmeter --check        # monitoring exit code
clawmeter update         # self-update
clawmeter tray           # run the tray in this session

Providers

Provider	Tracks
Claude	5h, 7d, model-specific windows
Codex	5h and weekly rate limits; banked reset-credit expiry when available
Antigravity	Separate weekly pools for Gemini models and Claude/GPT models
Gemini	24h Pro-model and Flash-model quotas; Code Assist tier checked when available
GitHub Copilot	Provider-reported premium, chat, and completion quotas when available
Grok/xAI	Grok weekly usage pool; API prepaid credits
Kimi	Usage and rate limits; cadence is provider-reported/experimental
OpenRouter	Wallet credit balance and finite API-key limits
JetBrains AI	Monthly credits
Kimi K2	Credit balance
Alibaba Coding Plan	Coding Plan 5-hour, weekly, and monthly quotas
Alibaba Token Plan	Personal Token Plan 5-hour, 7-day, and reset-credit data after one-time Model Studio quota connection
DeepSeek	Account balance only (read-only); no utilization, spend, or reset-time data

Unavailable providers stay hidden by default. Use clawmeter --all to see everything Clawmeter checked.

Model selection and quota windows are separate. Claude's model-scoped weekly windows use the names returned by Anthropic, including new model names. Codex's quota response does not identify the active model, so Codex rows stay labeled by the provider and the reported time window rather than guessing from the CLI model selection.

Provider maturity is binary and intentionally kept out of quota rows and the tray. The clawmeter providers inventory and --json metadata identify experimental integrations and link to provider maturity.

Automation should use the versioned --json machine interface, not parse terminal output. Its schemas, compatibility policy, diagnostic command, and consumer guidance are published with the repository.

Codex reset-credit visibility is read-only. Clawmeter shows available count and earliest expiry when Codex exposes banked resets locally, but it never redeems resets. Design notes and provider coverage are in Reset awareness.

Details

Agent integrations

clawmeter setup --all
clawmeter setup --claude-statusline
clawmeter setup --dry-run --all
clawmeter doctor

clawmeter statusline is cache-only, so Claude Code can call it frequently without refreshing provider APIs or burning quota. clawmeter status --agent is the high-precision pull command for Codex, Claude, Gemini CLI, or any other agent when quota context is useful.

tmux users can opt in explicitly:

clawmeter setup --tmux

Install options

Linux installer defaults to a user install: binary in ~/.local/bin, app launcher entry, no tray start, no launch-at-login, and no system package install. Pass --start to launch the tray now, or --autostart to enable launch-at-login.

curl -fsSL https://raw.githubusercontent.com/tnunamak/clawmeter/main/install.sh | sh -s -- --dry-run
curl -fsSL https://raw.githubusercontent.com/tnunamak/clawmeter/main/install.sh | sh -s -- --start --autostart
curl -fsSL https://raw.githubusercontent.com/tnunamak/clawmeter/main/install.sh | sh -s -- --uninstall

Windows users should prefer ClawmeterSetup.exe. WinGet is the package-manager path after acceptance. clawmeter-windows-amd64.exe is the portable fallback. install.ps1 remains an advanced scripting fallback with -LocalBinary, -Start, -Startup, and -Uninstall; if you use it directly, download the script first and run it from a folder you trust. Avoid copy-pasting download-and-execute one-liners.

macOS Homebrew installs a local app wrapper. To show it in Applications/Launchpad:

mkdir -p ~/Applications
ln -sfn "$(brew --prefix clawmeter)/Clawmeter.app" ~/Applications/Clawmeter.app

Configuration

Config file: ~/.config/clawmeter/config.yaml

clawmeter config show
clawmeter codex
clawmeter grok
clawmeter providers enable openrouter
clawmeter config disable copilot
clawmeter config set poll_interval 600
clawmeter config set warning_threshold 80
clawmeter config set critical_threshold 95

Launch at login

clawmeter tray --install
clawmeter tray --uninstall

clawmeter tray starts the tray for the current desktop session. For a persistent desktop tray, use the installer/Start Menu shortcut or clawmeter tray --install.

On macOS with Homebrew, you can also use:

brew services start clawmeter
brew services stop clawmeter

Provider credential sources

Provider	Source
Claude	Claude Code OAuth token
Codex	~/.codex/auth.json
Antigravity	~/.gemini/antigravity-cli/antigravity-oauth-token from agy login
Gemini	~/.gemini/ OAuth credentials
GitHub Copilot	~/.config/github-copilot/hosts.json
Grok/xAI	~/.grok/auth.json from grok login; or XAI_MANAGEMENT_API_KEY with optional XAI_TEAM_ID
Kimi	~/.kimi/credentials/kimi-code.json
OpenRouter	OPENROUTER_API_KEY or config; optional OPENROUTER_MANAGEMENT_KEY for wallet credits
JetBrains AI	IDE config files
Kimi K2	KIMI_K2_API_KEY or config
Alibaba Coding Plan	Dedicated Model Studio console login (bl auth login --console) or ALIBABA_CODING_PLAN_API_KEY / BAILIAN_CODING_PLAN_API_KEY (Coding Plan key only)
Alibaba Token Plan	One-time Model Studio quota connection via clawmeter providers connect token-plan; existing ~/.bailian session is reused
DeepSeek	DEEPSEEK_API_KEY or config

For Grok/xAI, grok login enables Grok weekly usage-pool tracking from the read-only grok.com billing surface. XAI_MANAGEMENT_API_KEY enables xAI API prepaid-credit tracking from the Management API; use a Management API key from xAI Console settings, not the model-serving XAI_API_KEY. Clawmeter does not create, rotate, delete, top up, or spend anything.

For Alibaba Coding Plan, Clawmeter reads the official Model Studio CLI's console-login session from its dedicated Coding Plan profile or ~/.bailian. It sends only the read-only quota query, never reads browser cookies and never calls a model or plan-management endpoint. Personal Token Plan remains a separate provider and session profile.

For Alibaba Token Plan, run clawmeter providers connect token-plan once to authorize the official Model Studio console session. Clawmeter then reads only the read-only quota and reset-card operations. BAILIAN_TOKEN_PLAN_API_KEY continues to be useful for model requests, but it does not provide account-level Token Plan quota and is never treated as quota authorization. If the official Bailian CLI is missing, Clawmeter prints Alibaba's documented install command; it does not silently download executable code.

DeepSeek is read-only balance semantics. Clawmeter calls only the documented GET /user/balance endpoint and reports the account balance per currency; it never exposes utilization percentage, spend, quota totals, or reset timing, because DeepSeek's balance API does not provide them. Clawmeter never tops up, spends, or rotates the key.

Build from source

git clone https://github.com/tnunamak/clawmeter.git
cd clawmeter
make install          # CLI only
make install-tray     # with system tray support

Tray builds require CGO. Linux also needs libayatana-appindicator3-dev.

How It Works

Clawmeter reads existing credentials from your AI coding tools and queries their usage APIs. Results are cached at ~/.cache/clawmeter/usage.json for 60 seconds, so the CLI and tray do not hammer provider APIs. See Privacy Policy, Security Policy, and Third-party components.