herdr-agent-usage (senna-lang) plugin
herdr-agent-usage
A Herdr plugin with a limits pane: context fill, prompt cache and remaining subscription allowance for each agent.
- 66 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The plugin reads local agent files, including credential metadata, and may use a browser cookie through the keychain for OpenCode Go windows.
- It queries provider servers with your tokens when Grok and OpenCode Go are enabled.
Install
- Works in
Manual install
herdr plugin install senna-lang/herdr-agent-usageHerdr 0.7.5 or newer is required. In non-interactive shells add `--yes`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The plugin reads local agent files, including credential metadata, and may use a browser cookie through the keychain for OpenCode Go windows.
- It queries provider servers with your tokens when Grok and OpenCode Go are enabled.
This is third-party code. Review the repository files before installing.
What it does
The Agent Usage plugin for the Herdr terminal multiplexer shows how much the agents running in its panes consume. The sidebar label of each pane shows how much of the context window the session fills, the prompt-cache hit rate and what remains in the tightest limit window, for example the 5-hour one. A separate pane gathers 5-hour, 7-day and 30-day windows for Claude, Codex, OpenCode Go and Grok, with a countdown to reset and a note on which open pane burns the limit. For API keys it counts tokens and provider cost per day, week and month instead of a subscription. When the remainder drops below the 50, 20, 10 and 5 percent thresholds, a toast notification appears.
Who it is for. Herdr users who keep several subscription-based agents in panes and want to see limit consumption before work stalls.
Good fit when
- Claude Code and Codex run in several panes and the 5-hour limit ends unexpectedly.
- A session has grown and you must decide whether to start a new one before the context overflows.
- An agent uses a direct API key and you want to see tokens and dollars spent per day.
- You hold subscriptions on several accounts and need each window's remainder in one place.
- A low prompt-cache hit rate hints that a session is worth restarting.
Not a fit when
- You do not work in Herdr: the plugin only plugs into its sidebar and commands.
- You need exact figures as in the account console: values come from local files and can differ from server-side windows.
- You use Windows: only macOS and Linux are supported.
Example request
Open the Agent Usage limits pane and tell me which open pane has the least left in the 5-hour window.Limitations
Herdr 0.7.5 or newer and macOS or Linux are required. Installation builds the `usagebar` binary with a local Go 1.25 or downloads a prebuilt one from releases. Installation does not change `~/.config/herdr/config.toml`, so sidebar rows and toasts are enabled with the separate `usagebar.setup` action. Data comes from local agent files and can differ from official windows. OpenCode Go windows need an opencode.ai cookie, otherwise a local-database estimate remains. For Cursor only context is shown, with no limits.
How to disable. Remove the plugin with Herdr tools and delete the sidebar rows it added to `~/.config/herdr/config.toml`. Status snapshots sit in each agent's `herdr-usagebar` folder.
FAQ
How do I install Agent Usage in Herdr?
Run `herdr plugin install senna-lang/herdr-agent-usage`, adding `--yes` in a non-interactive shell. Then run `herdr plugin action invoke usagebar.setup` and reload the configuration with `herdr server reload-config`.
Which agents does the plugin support?
Claude Code, Codex, OpenCode, Grok and others such as Hermes Agent, Pi and Devin. Full limit windows are not available for all: Cursor, for example, shows only context fill.
Where do the numbers come from?
From files agents already keep locally: sessions, Codex rollouts, `~/.claude.json`. Network requests go only for OpenCode Go windows and Grok credits and are skipped without the needed credentials.
How does the plugin differ from the other herdr-agent-usage?
This Go project adds cache and limit rows to the sidebar label, low-remainder warnings and a pane with 5-hour, 7-day and 30-day windows. The levi-qiao version groups tabs by space.
Does the pane replace the provider's billing page?
No. Values come from local files and can differ from server-side windows if you worked on another machine. Open the provider's console for exact sums.
Discussion
No questions or reviews yet.
Related
PluginsA Herdr plugin that names tabs and panes from the directory, Git branch and agent activity so sessions stay distinct.
Local gateway for coding agents: one setup for model providers, call tracing and per-request cost.
A local dashboard for Claude Code and Codex sessions: who is working, who waits for you, plus a 3D aquarium and Stream Deck
hermesd shows Hermes Agent gateway, sessions, token spend, cron jobs and logs in one terminal, without writing to its state.
A plugin that teaches Claude Code and Codex to drive the agterm macOS terminal via agtermctl: sessions, panes, overlays, status
Tokscale
tokscale
A CLI with an interactive TUI that tracks token usage and cost across AI coding agents: Claude Code, Codex, Copilot, Cursor and more
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| herdr-agent-usage (senna-lang) (this card) | no | 66 | |
| herdr-agent-usage | no | 160 | groups tabs by Herdr space; the senna-lang plugin adds cache, warnings and a pane of 5-hour, 7-day and 30-day windows |
| ccusage | no | 19,425 | counts usage from logs on the command line; the plugin shows it right in Herdr panes |
README in short
The project description starts with monitoring agent context and limits inside Herdr. It details data sources per agent, setup for several Claude, Codex and Grok accounts and upstream drift monitoring.