herdr_agents_tracker

Why · Features · Install · Use · Configure · Providers · Privacy · FAQ

_{Screenshots use demo accounts and made-up numbers.}

Why this one

Claude ████░░░░░░ 52% 2h12m (100% in 1h40m)

⛁ 28% 72k · ~12% of 5h
⛁ 15% 148k · ~2% of 5h

Claude 5h limit has reset
Waiting on it: api server, web. They can go on.

Everything it answers

How it works

flowchart LR
    subgraph Sources["Read locally, no credentials"]
        C["Claude Code<br/>get_usage + statusLine"]
        X["Codex<br/>app-server"]
        O["OpenCode Go<br/>opencode.db"]
        S["Session files<br/>token counts only"]
    end
    R(["Collector<br/>every 5 min and<br/>after each turn"])
    D[("Cache and<br/>history")]
    subgraph Herdr
        T["Tab bar<br/>every 30 s"]
        A["Agents panel<br/>meters"]
        P["Dashboard<br/>prefix+u"]
        N["Notifications"]
    end
    J["CLI<br/>--json / --check"]
    C --> R
    X --> R
    O --> R
    S --> R
    R --> D
    D --> T
    D --> A
    D --> P
    D --> N
    D --> J

A closer look

Tab bar: all accounts at a glance

One entry per account: logo, bar, % used and time until reset, for every limit window. A model's
own limit shows its name (0% Fable). When the tab bar runs short of room, it drops model limits,
then reset times, then bars, but every account stays visible.

Agents panel: a meter under every agent

Under each Claude Code and Codex agent:

• Context meter: how full its context window is, coloured by level.
• Its part of the limit: ~12% of 5h, updated after every turn.
• Stopped at a limit? The meter shows limit · resets 22:20 instead. A minute after the
  reset, one notification names every agent that was waiting.

Dashboard: prefix+u

Every limit with its bar, pace and a trend line across the window, then your token history:
today, 7 days, 30 days or all time, with a daily heatmap and totals by account, model, project
and session.

Numbers you can trust

It never shows a misleading 0%. Every state has its own label:

[!TIP]
Several accounts per provider are fine (personal and work, say): each keeps its own cache,
history and alerts, and they're never merged.

Install

[!IMPORTANT]
Requirements: Herdr 0.8.2+ · Python 3.11+ · macOS or Linux.
macOS ships Python 3.9, so run brew install python once; the install stops with a message if
no 3.11+ is found.

# 1. Install the plugin (shows a preview; confirm it)
herdr plugin install VHemanth45/herdr_agents_tracker

# 2. Run the setup guide (shows its plan; applies when you answer "y")
herdr plugin action invoke setup --plugin herdr_agents_tracker

That's it. Setup:

• adds the tab-bar summary, a prefix+u dashboard key and a prefix+shift+u refresh key;
• adds the context meter to the Agents panel;
• writes a starter config listing the accounts it found;
• wraps your Claude Code statusLine so Claude's own limit numbers are saved (your command still
  runs, unchanged);
• reloads Herdr's config without restarting Herdr or touching running agents.

[!NOTE]
Every line setup writes ends with # usage-tracker, every file is backed up first, and running
it again changes nothing.

git clone https://github.com/VHemanth45/herdr_agents_tracker.git
cd herdr_agents_tracker
herdr plugin link "$PWD"
bin/usage-tracker setup --claude-statusline --apply

Use

Herdr's action menu also has Usage: open dashboard · refresh now · show diagnostics · setup guide.

How fresh is it? The tab bar reads a local cache every 30 s. Limits are re-read every
5 minutes and right after an agent finishes a turn. Claude's statusLine reports its 5h and 7d
limits as you work.

For scripts

usage-tracker status --json                    # every account's limits and forecast, as JSON
usage-tracker status --check 90 --profile claude || echo "Claude is nearly out"

Plain status (what the tab bar runs) always exits 0, so the tab bar is never hidden by it.

Configure

Your config: ~/.config/herdr/plugins/config/herdr_agents_tracker/config.toml
(herdr plugin config-dir herdr_agents_tracker). config.example.toml
lists every option with comments.

Notifications follow Herdr's [ui.toast] delivery, which must be "herdr" or "system".

Providers

Provider	Limits it shows	Where they come from	Tested
Claude Code	5h, 7d, per-model weekly (Fable, Sonnet), plan	Claude Code itself (claude -p answering get_usage) and your statusLine
Codex	Every window Codex reports, plan	codex app-server → account/rateLimits/read, or the last snapshot in a session log
OpenCode Go	Estimated 5h / 7d / 30d spend against the published Go caps	Costs in the local opencode.db (the official meter isn't read)
GitHub Copilot CLI	Monthly premium requests (chat and completions on Copilot Free), plan	gh api /copilot_internal/user: the account gh is signed in to
Amp	Amp Free (daily), subscription or tier usage, plan	amp usage
Gemini CLI	Daily quota per model (Pro, Flash, …), plan	Google's Code Assist quota with the Gemini CLI's sign-in. Google sign-in accounts on a Code Assist plan only (Google stopped serving personal accounts through Gemini CLI in 2026). Opt-in
Cursor	Included usage of the billing cycle: total, Auto and API, plan	Cursor's dashboard service with Cursor's sign-in. No token history (Cursor keeps none on disk). Opt-in
Grok	Weekly credit %, monthly usage	Grok's billing endpoint with the Grok CLI's sign-in. Opt-in

Limits are account-wide, so they include use outside Herdr. Windows are shown separately and never
summed. Token history comes from session records on this machine only. API-key accounts never get
invented subscription limits, and no prices or spend estimates are shown.

Privacy: what it reads

Everything is a local file or the provider's own CLI. The plugin makes no network request of its
own (except the opt-in Gemini, Cursor and Grok) and sends nothing anywhere.

[!CAUTION]
Never read: ~/.claude/.credentials.json, Codex's auth.json, the GitHub CLI's or Amp's
sign-in, the macOS Keychain, browser cookies, or the content of any conversation. It never switches the account an agent uses, and
it types into an agent only if you turn on [resume], and then only the resume prompt, once per
reset.

It writes its own state (~/.local/state/herdr/plugins/herdr_agents_tracker), the marked lines in
Herdr's config.toml, and the statusLine wrapper in Claude's settings.json.

FAQ

No. Herdr's code is untouched: this is a plugin. Setup only adds lines to Herdr's config.toml,
each ending with # usage-tracker, and uninstall --apply removes exactly those lines.

Yes. Each provider is independent: use it with Codex, Copilot, Amp, Gemini or any other alone, and accounts you
don't have are simply not shown.

The agent's share of the account's tokens since the 5-hour window opened (its subagents included,
cache reads left out because they count for little against the limit), times the window's % used.
It's an estimate from this machine's session records, hence the ~. Turn it off with
context.share = false.

Only if you set [resume] enabled = true. Then, a minute after a limit resets, each agent that
stopped at it is sent continue, and only if it's still idle at that limit error. An agent that's
busy, or that you already continued yourself, is left alone.

The plugin uses only the standard library, including tomllib (added in 3.11), so there is
nothing to pip install. Run brew install python once; the install stops with a clear message
if no 3.11+ is found.

Limits are re-read every 5 minutes and after each turn, so they can lag briefly. OpenCode Go's
numbers are estimates from local costs.

Update, remove, troubleshoot

Update (your settings are kept; see CHANGELOG.md):

herdr plugin install VHemanth45/herdr_agents_tracker

Remove (backs up each file first and removes only lines marked # usage-tracker):

root=$(herdr plugin list --plugin herdr_agents_tracker --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["result"]["plugins"][0]["plugin_root"])')
"$root/bin/usage-tracker" uninstall                  # dry run: shows what would go
"$root/bin/usage-tracker" uninstall --apply          # remove the config lines, restore statusLine, unregister
"$root/bin/usage-tracker" uninstall --apply --purge  # also delete the plugin's config and state

Something off?

• Run Usage: show diagnostics (or bin/usage-tracker diagnostics): each account's source,
  last attempt, errors, next refresh, history coverage and the state of the integration.
  Credentials are never shown.
• Collector log: ~/.local/state/herdr/plugins/herdr_agents_tracker/collector.log.
• Nothing in the tab bar? Herdr hides the summary when it doesn't fit beside the tabs; try a
  smaller status.max_width or status.format = "compact".

Roadmap

Ideas, not promises. Open an issue to vote for one or to help:

• Turns left per agent: ~9 turns left before the 5-hour limit, at its recent pace.
• Runaway-agent alert: one agent using a large share of the limit in minutes.
• Usage by git branch or worktree: "feature/login used 23% of this week's limit".
• Daily budget for the weekly limit: 9%/day keeps you under until the reset.
• Live testing for OpenCode Go, Copilot, Amp, Gemini, Cursor and Grok.

Adding a provider is one adapter module; CONTRIBUTING.md explains how.

Development

• Tests: python3 -m unittest discover -s tests (synthetic fixtures and temporary directories;
  they never touch real accounts or Herdr config).
• docs/internals.md: how it works, the modules, adding a provider, and the
  Herdr 0.8.2 behavior this builds on.

License

MIT. Data-source research drew on
senna-lang/herdr-agent-usage (MIT, © 2026 senna)
and on Orca's usage view as a behavioral reference; no code from either is included.