Shows current provider usage (Claude / Codex / OpenCode Go / Neuralwatt) in a Herdr modal popup, with a bar per rate-limit window, plan, and reset times. Requires herdr ≥ 0.7.4.
- Anthropic (Claude Code): OAuth usage against
https://api.anthropic.com/api/oauth/usage. Credentials are read from~/.claude/.credentials.json($CLAUDE_CONFIG_DIRmay override the directory) and, on macOS, the Keychain entryClaude Code-credentials; the freshest valid token wins. When the access token is expired the refresh-token grant is invoked againsthttps://platform.claude.com/v1/oauth/token(client id9d1c250a-e61b-44d9-88ed-5944d1962f5e, the value Claude Code itself uses); the rotated refresh token is written back to the same source it was read from so the CLI does not desync. 5-hour and 7-day windows. Responses are cached on disk and the endpoint's rate limits (429 + Retry-After) are respected. - OpenAI (Codex CLI): the
rate_limitssnapshots Codex writes to its local session files (~/.codex/sessions/**/*.jsonl). No network, no credentials. - OpenCode Go: rolling 5-hour, weekly, and monthly usage aggregated from
the local OpenCode SQLite history at
~/.local/share/opencode/opencode.db. Cost is summed over assistant messages withproviderID = "opencode-go"against the plan's fixed dollar windows ($12 / 5h, $30 / week, $60 / month) anchored to the first usage timestamp. Reuses the same on-disk history CodexBar's local reader uses (codexbar PR #1021) — no dashboard login, no cookie copy. - Neuralwatt: credit balance, per-key allowance, and subscription energy allocation from the official near-real-time quota API.
Credentials are never printed or included in cached payloads.
herdr plugin install gecm0/herdr-plugin-agents-usageOr link a local checkout while developing:
herdr plugin link /path/to/herdr-plugin-agents-usageherdr plugin pane open --plugin gecm.agents-usage --entrypoint usager refreshes, any other key closes. Recommended keybinding in
~/.config/herdr/config.toml:
[[keys.command]]
key = "prefix+u"
type = "shell"
command = "herdr plugin pane open --plugin gecm.agents-usage --entrypoint usage"
description = "provider usage"Usage is read from ~/.local/share/opencode/opencode.db; the only setup is to
have run opencode at least once so the database and assistant-turn history
exist. No workspace ID, dashboard cookie, or browser export required.
If OpenCode later switches to a different database location, override the path via the environment that starts Herdr:
export OPENCODE_GO_DB="/custom/path/opencode.db"The plan-tier dollar limits ($12 / 5h, $30 / week, $60 / month) are constants in
usage.py (OPENCODE_GO_LIMIT_USD); bump them if OpenCode changes plan tiers.
If OpenCode ships the pending
public usage endpoint,
this reader can be swapped for it.
The API key is resolved in this order:
NEURALWATT_API_KEYenvironment variable.~/.config/neuralwatt/api_key(one-line file, mode 600).- The active Neuralwatt token account in CodexBar's config
(
~/.config/codexbar/config.json, legacy~/.codexbar/config.json) — i.e. if CodexBar already shows your Neuralwatt usage, this plugin reads the same key with no extra setup.
If none are present, create an API key under Neuralwatt Dashboard → API Keys and use any of the above. The simplest is the official environment variable:
export NEURALWATT_API_KEY="sk-..."For Herdr processes that do not inherit your shell environment, store the key in the location used by Neuralwatt's own usage tooling:
mkdir -p ~/.config/neuralwatt
read -rsp "Neuralwatt API key: " key && printf '\n'
printf '%s\n' "$key" > ~/.config/neuralwatt/api_key
unset key
chmod 600 ~/.config/neuralwatt/api_keyThe modal will show available credits, key allowance, and subscription percentages.
API details: Neuralwatt quota API and OpenCode integration.
python3 usage.py probe # parsed provider diagnostics
python3 usage.py selftest # formatting/parsing assertions
herdr plugin log list --plugin gecm.agents-usage