herdr-agent-quota

Never hit a quota limit mid-task. Live Claude Code, Codex, Grok, and
Agy/Antigravity subscription usage, in Herdr's agent sidebar.

中文文档：README.zh-CN.md

● Owner · Claude
  hi                     ← what that pane is actually working on
  5h 100% reset 3h07m
  week 31% reset 2d3h

A real Herdr workspace: Claude shows separate five-hour and weekly reset
ETAs, Codex and Grok show their weekly windows, and each agent card uses the
latest user prompt rather than an AI-generated status.

• Four CLIs, one sidebar — Claude Code, Codex, Grok, Agy/Antigravity.
• Three or four lines per pane — provider, one line per quota window, and
  the latest user prompt.
• Local only — no usage data uploaded, no browser cookies, no keychain
  scraping, and credentials are never written or refreshed.
• Never lies to you — a failed refresh keeps the last good number instead
  of flashing unavailable, and API-key auth is never shown as a subscription
  quota.
• Fully reversible — one action sets it up, one action puts your config
  back exactly as it was.

For a downloaded checkout, one command applies every reversible integration
(quick start):

./install.sh

The screenshot is a real local Herdr session. The values and topic text are
examples from that session; they are not hard-coded in the plugin.

Time-aware quota health

Quota colors answer “will this allowance last until reset?” instead of applying
a fixed percentage threshold. For each available 5-hour or 7-day window, the
plugin computes:

time_left  = (reset_at - now) / window_duration
quota_left = remaining_percent / 100
health     = quota_left / time_left

• Green — health >= 1: quota is being consumed no faster than time.
• Amber — health < 1: current usage is ahead of the sustainable pace.
• Red — health < 1 and less than 20% quota remains: exhaustion risk is
  both immediate and material.
• Amber fallback — reset data is missing or expired, so the plugin avoids
  claiming that the quota is safe.

This explains the screenshot: Claude's 5-hour 89% is amber because slightly
more than 89% of that window remains; its weekly 24% is green because only about
13% of the week remains. Grok's weekly 17% is red because about 69% of its
window remains and the quota is already below 20%. The calculation is shared by
every provider adapter; only the window data differs.

Quick start

Requirements: Herdr 0.8.0+, Rust 1.95+, macOS or Linux, and at least one
supported CLI. If you downloaded this repository, the one-step installer does
the build, link, enable, and reversible configuration for you:

./install.sh

To restore the previous sidebar/statusLine configuration and unlink the plugin:

./uninstall.sh

The scripts are idempotent. They leave the local quota snapshots in Herdr's
plugin state directory; those contain no credentials and can be removed later
if desired.

The equivalent Herdr commands are:

herdr plugin link . --enabled
herdr plugin action invoke herdr-agent-quota.configure

The configure action consistently uses Herdr's plugin state, applies the
sidebar rows, installs or repairs the reversible Claude and Agy statusLine
collectors, and reloads Herdr's config. You can
run it again safely from Herdr's action menu as Install / repair agent quota.
Use Refresh agent quota for a one-shot refresh, or
press prefix+shift+r after configuration. The shortcut force-fetches Codex
and Grok, then republishes the latest Claude and Agy statusLine snapshots. Run
the same action from a shell with:

herdr plugin action invoke herdr-agent-quota.refresh

Herdr plugin v1 does not currently let plugins add buttons to the native agent
group header, so the shortcut is the closest stable one-step entry point.
Selecting a pane also runs a provider-only refresh, debounced to once per
minute. While any agent is working, one global background watcher polls the
working provider set once per minute, publishes fresh cache values, and performs
one final debounced pass when each provider settles. These pulses never read
terminal content, and a pane currently viewing scrollback receives no metadata
write until it returns to the bottom.

The default poll interval is 60 seconds. To persist another value (30 seconds to
one hour), pass it during installation:

./install.sh --watch-interval-seconds 300

Or update an existing installation with the same environment override:

HERDR_AGENT_QUOTA_WATCH_INTERVAL_SECONDS=300 \
  herdr plugin action invoke herdr-agent-quota.configure

Each poll uses one global coordination lock and one herdr agent list call.
Provider network fetches are independently capped at one per 60 seconds by the
existing refresh markers, even if a shorter custom poll interval is requested.
The watcher never sends prompts, starts a new login, refreshes credentials, or
consumes model/chat tokens; a manual --force refresh is the explicit exception.

Preview the changes without writing anything:

./target/release/herdr-agent-quota configure --check

Remove every plugin-owned config edit and restore previous Claude/Agy
statusLine commands with the one-click Uninstall agent quota configuration
action, or invoke it from a shell (the ./uninstall.sh wrapper above also
unlinks the plugin):

herdr plugin action invoke herdr-agent-quota.uninstall

After that action finishes, herdr plugin unlink herdr-agent-quota can remove
the local plugin registration too. Configuration writes intentionally run
through plugin actions so all collectors use the same Herdr state directory.

The setup preserves Herdr's native state dot and plane/tab label. It only adds
the provider, usage, and topic tokens, so the original Herdr agent indicator is
not removed. Uninstall removes the plugin-owned rows and restores previous
Claude and Agy statusLine commands. Older plugin-owned Grok response hooks are
removed during configure; the single global watcher now covers Grok as well, so
long turns no longer start one refresh command per tool call.

Supported CLIs

Versions above were checked on the development machine on 2026-08-15. The
parser follows the provider fields rather than hard-coding these version
strings, so newer compatible CLI releases can continue to work.

The sidebar shows percentage remaining and the time until each reset, not
token counts. Codex and Grok expose their weekly window. Claude Code and Agy
expose both five-hour and weekly windows. Reset ETAs use minutes below one hour,
hours and minutes below one day, and days plus hours above one day. During a
working turn, one short-lived global watcher polls once per configured interval,
coalesces active fetches, and exits when all selected providers settle. The
sidebar does not run a permanent daemon.

A failed refresh never replaces a successful cached value with unavailable;
a provider without any successful snapshot is shown as N/A until its first
usable event.

Agy / Antigravity collection

Agy sends its quota snapshot to the plugin through its native one-shot
statusLine hook. The configure action installs it automatically, backs up and
chains an existing command, and restores that command on uninstall. The plugin
collector itself emits no status-line text: it reads JSON from stdin, writes
only sanitized percentages to the local plugin cache, and exits. It is not a
resident process and does not use browser cookies or a private API.

What the sidebar rows mean

The default rows are deliberately compact and keep the provider name only
once:

[ui.sidebar.agents]
row_gap = 1 # herdr-agent-quota
rows = [
  ["state_icon", "tab", { token = "$quota_provider", bold = true, dim = false }],
  [{ token = "$quota_topic", dim = false }],
  [{ token = "$quota_5h_normal", fg = "#84b084", bold = true, dim = false }],
  [{ token = "$quota_5h_warning", fg = "#cdaa65", bold = true, dim = false }],
  [{ token = "$quota_5h_danger", fg = "#ca6470", bold = true, dim = false }],
  [{ token = "$quota_week_normal", fg = "#84b084", bold = true, dim = false }],
  [{ token = "$quota_week_warning", fg = "#cdaa65", bold = true, dim = false }],
  [{ token = "$quota_week_danger", fg = "#ca6470", bold = true, dim = false }],
]

• state_icon and tab are Herdr's built-in status and plane labels.
• $quota_provider is Claude, Codex, Grok, or Agy.
• Default provider labels use recognizable brand colors without affecting quota
  health: Claude soft orange, Codex pastel blue, Grok soft white, and an
  Antigravity-inspired mint for Agy.
• $quota_topic comes before the quota rows so the card reads as agent, task,
  then resource status.
• Each window publishes exactly one styled variant. Color follows runway rather
  than a fixed quota threshold: remaining quota is compared with the percentage
  of window time still left. At or ahead of pace is green; behind pace is
  amber; behind pace with less than 20% quota remaining is red. Missing or
  expired reset data uses the warning color. Herdr hides all absent variants,
  including the unsupported 5h row for Codex/Grok.
• row_gap = 1 adds one blank row between agent cards. An existing explicit
  row_gap value is preserved.
• $quota_5h, $quota_week, and $quota_summary remain available for custom
  unstyled layouts.

Herdr 0.8 only accepts fixed hex colors for styled tokens, not semantic theme
colors. The default palette uses soft, high-luminance green, amber, and red
tones to reduce eye strain on Herdr's dark sidebar while keeping each health
state easy to scan.

Provider styling uses Herdr's static rows_by_agent projection, while quota
health remains dynamic metadata. This keeps branding and health logic separate
and avoids spending additional metadata-token capacity on static labels.

Herdr plugin v1 accepts text tokens, not provider image components. For that
reason the default layout uses the readable provider name and keeps Herdr's
native dot instead of adding low-recognition Unicode or SVG markers. The
checked-in docs/icons/ assets are optional visual references;
they are not injected into the native sidebar.

The topic reader is event-driven: it scans recent pane output after an agent
event and extracts the latest user prompt. It deliberately leaves the topic
empty when no prompt is found instead of showing an AI-generated terminal title
such as Thinking or Executing. It does not show the working directory.

Data sources and privacy

• Codex: the local official app-server JSON-RPC
  rate-limit response. The plugin accepts the seven-day window by duration,
  rather than assuming which field is primary. API-key authentication is
  intentionally not mislabeled as a ChatGPT subscription quota.
• Grok: the local ~/.grok/auth.json login key is read in memory and sent
  to the weekly billing endpoint used by the Grok CLI. The response is accepted
  only when it identifies a weekly period. This is SuperGrok usage, not xAI
  developer/API-team billing. The unified watcher and the existing 60-second
  debounce limit active requests; it never logs in or refreshes the key.
• Claude Code: the official statusLine JSON hook
  supplies the five-hour and seven-day values. A previous statusLine command is
  backed up, chained, and restored by the uninstall action; the active-turn
  watcher republishes each new snapshot without calling Herdr from that hook.
• Agy/Antigravity: the official /usage and statusline docs
  supply Gemini and third-party pools. When both pools exist, the sidebar uses
  the lowest remaining percentage so the single Agy row is conservative; its
  statusLine cache is published by the same active-turn watcher.

Snapshots and refresh markers stay in Herdr's plugin state directory. No usage
data is uploaded, browser cookies or browser keychains are read, and provider
credentials are never refreshed or written. Provider failures leave the last
successful local value visible.

The Grok CLI billing endpoint is an internal CLI contract, not a public xAI
developer API stability promise. If it changes, the plugin keeps the previous
weekly value instead of clearing the sidebar.

Troubleshooting

Development

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features --locked
cargo build --release --locked

CI runs these on Linux and macOS for every pull request.

CONTRIBUTING.md covers the design rules every parser
follows and how to add a provider. Security reporting is in
SECURITY.md, and released changes are in
CHANGELOG.md.

The Grok source investigation is documented in
docs/research/codexbar-grok-usage.md,
and the implementation contract is in
docs/plans/herdr-agent-quota-implementation.md.

Contributing

Adding a CLI is deliberately small: a pure parse_* function, a redacted
fixture, and a test. The rules it has to satisfy are in
CONTRIBUTING.md.

If this saved you a pane switch, a ⭐ helps other Herdr users find it. A bug
report with your CLI version is even better — it decides which provider parser
gets fixed next.

License

MIT. This project is not affiliated with Herdr, OpenAI, Anthropic, xAI, or
Google.