herdr-openusage

A Herdr plugin that runs OpenUsage — the terminal dashboard for quota, usage and spend across Claude Code, Codex, Antigravity, OpenCode, DeepSeek and 30+ other providers — inside a Herdr pane.

Install

herdr plugin install <owner>/herdr-openusage

The build hook reuses an openusage already on your machine. If there is none, it downloads the pinned release (currently 0.26.1) into the plugin's vendor/ directory and verifies its SHA-256 checksum. Set OPENUSAGE_VERSION before installing to pin another release.

OpenUsage collects data through a small background helper. The first time the dashboard opens it offers to install it (openusage telemetry daemon install, a systemd user service on Linux or a launchd agent on macOS).

Use

From the Herdr command palette:

Action	What it opens
Open OpenUsage dashboard	openusage for this machine and user
Open OpenUsage hub view	openusage hub-view $OPENUSAGE_HUB_URL, aggregated across machines and accounts

From the CLI: herdr plugin action invoke openusage.open or herdr plugin pane open --plugin openusage --entrypoint dashboard.

Configure

Plugin settings live in an env file in the plugin config directory, so keys never land in the plugin checkout:

cfg="$(herdr plugin config-dir openusage)"
install -m 600 /dev/null "$cfg/.env"
$EDITOR "$cfg/.env"

Variable	Purpose
DEEPSEEK_API_KEY, OPENCODE_API_KEY, …	API keys for providers OpenUsage detects from the environment
OPENUSAGE_HUB_URL	Hub to show in the hub view, e.g. http://hub.example:9190
OPENUSAGE_HUB_TOKEN	Bearer token, if the hub requires one
OPENUSAGE_BIN	Use a specific openusage binary
OPENUSAGE_EXTRA_PATH	Extra directories to search for agent CLIs

The Herdr server may run with a minimal PATH. The pane adds the usual per-user install directories (~/.local/bin, ~/go/bin, ~/.opencode/bin, Homebrew…) so OpenUsage can still detect claude, codex, agy and opencode.

Provider notes:

• Claude Code, Codex: detected automatically from ~/.claude and ~/.codex.
• Antigravity: run openusage integrations install antigravity once so agy writes its status line for OpenUsage.
• OpenCode: keys stored by opencode auth login are adopted automatically.
• DeepSeek: set DEEPSEEK_API_KEY.

Several accounts, users or machines

OpenUsage reads one set of local agent directories per OS user. To see several accounts together, run OpenUsage (with its daemon) once per user or account, have each one push to a hub, and open the hub view here:

// ~/.config/openusage/settings.json of every user/account that reports
{ "export": { "target": "http://hub.example:9190", "machine_name": "laptop-claude-work" } }

# on the hub host
OPENUSAGE_HUB_TOKEN=… openusage hub --headless --listen 0.0.0.0:9190

Development

bash bin/ensure-openusage.sh        # `plugin link` does not run build hooks
herdr plugin link "$PWD"
herdr plugin action invoke openusage.open
herdr plugin log list --plugin openusage

License

MIT. OpenUsage itself is MIT-licensed by its authors.