herdr-agent-usage CLI
A Herdr plugin shows model, context and remaining quota for each agent in the sidebar, grouped by workspace.
- 156 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Reads stored login tokens of several agents, including macOS Keychain, and sends requests to providers with them.
- Installation creates hooks and integrations in agent settings.
Install
- Works in
Manual install
git clone https://github.com/levi-qiao/herdr-agent-usage.git
cd herdr-agent-usage
./install.shThe script builds the binary, links the plugin into Herdr and runs configuration. The `--agent claude,codex,omp` flag selects agents.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Reads stored login tokens of several agents, including macOS Keychain, and sends requests to providers with them.
- Installation creates hooks and integrations in agent settings.
This is third-party code. Review the repository files before installing.
What it does
herdr-agent-usage extends the Agent panel of the Herdr terminal multiplexer. Each agent tab shows provider, model, context fill and subscription meters for 5 hours, 7 and 30 days, and the icon colour tells whether the agent is working, done or idle. Tabs that share one subscription collapse into a single row. Quota comes from each agent's own source: Codex through its app-server, Claude Code through the statusLine, Cursor, Grok, Devin and OpenCode through their service endpoints using the current login. Low-quota notifications are off by default. Layout, fields and spending pace are set in the `prefix+shift+q` panel.
Who it is for. Herdr users who run several agents on different subscriptions and are tired of opening each one to check the remaining limit.
Good fit when
- Three or four tabs run Claude Code, Codex and Cursor in parallel, and it matters whose 5-hour window is running out.
- Two tabs burn one subscription, and the shared remainder matters more than two identical meters.
- A session's context is nearing its limit, and it should be visible without a command.
- Quota spending pace has to be compared with the time left in the window.
Not a fit when
- Herdr is not in use, because the plugin works only inside its sidebar.
- You need Windows, since macOS and Linux are supported.
- You are not ready to give the plugin access to agent login tokens.
Example request
Install herdr-agent-usage only for the agents found on my machine, check the icons in this terminal and show which subscriptions it detected.Limitations
Herdr 0.9.0 or newer, the Rust toolchain from `rust-toolchain.toml`, macOS or Linux and a supported agent CLI are required. Installation builds a binary and creates hooks in agent settings. Cursor and Muse on macOS need a one-time Keychain approval on first run. Icons render after a terminal font is configured. Kilo shows only a monthly meter, and a shared credit balance shows no percentage. The plugin reads stored agent tokens and uses them against provider service endpoints.
How to disable. Disable the plugin in Herdr and remove the hooks and integrations that `install.sh` created. Saved settings and cache stay local and are removed by hand.
FAQ
Which agents are supported?
Claude Code, Codex, Cursor, Grok, Devin, OpenCode, Pi, omp, Kilo Code, Muse Code and Agy. The `--agent` flag selects the set.
How do I upgrade the plugin?
From the repository directory run `git pull --ff-only` and then `./install.sh`. Preferences are kept.
Why does it need Keychain access?
On macOS, Cursor and Muse keep the login token in Keychain, and the plugin reads it to query quota. The approval is granted once.
Does it show Claude Code quota?
Yes, through the statusLine: 5-hour and 7-day windows. Your own statusLine stays, and the plugin only appends spending pace.
Are there low-quota notifications?
They are off by default. Set a threshold in the `prefix+shift+q` settings panel.
Discussion
No questions or reviews yet.
Related
CLI toolsThe /myoffice command opens a browser office showing what every agent on your machine is doing: thinking, waiting for you or done.
Agent Standup shows Claude Code, Codex and Mistral Vibe sessions as a live team call: who works, who waits.
Voice control of Claude Code and Codex sessions on your machines: a small agent on each box links it to the pitupitu cloud.
Local browsing, search and cost tracking for Claude Code, Codex and other agent sessions in one web UI
Mac screen HUD for agents: quotas, tokens and sessions of Claude Code, Codex and more, plus a built-in MCP server.
A CLI that shows an agent the remaining quota of Claude, Codex, Cursor, Copilot and 15 more services in one compact report.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| herdr-agent-usage (this card) | no | 156 | |
| herdr | no | 48,519 | the multiplexer itself, which keeps agent sessions alive; this plugin adds subscription limits to its panel |
| ccusage | no | 19,337 | counts tokens and cost from local logs; this plugin shows current remaining quota in the Herdr panel |
README in short
One background watcher serves all agents. Requests are debounced for 60 seconds, with a final refresh after a turn settles.