CLI Usage Bar

See your remaining Codex and Cursor quota without leaving BB.

CLI Usage Bar adds a compact native card immediately above BB's sidebar footer. It reads the authenticated usage reported by supported local CLIs and shows the percentage remaining, with no extra dashboard or panel to manage.

Features

• Shows remaining quota for Codex and Cursor Agent in one compact row.
• Refreshes automatically every five minutes.
• Includes a manual refresh button with a clear loading state.
• Uses BB theme tokens, so it follows light and dark themes.
• Hides missing CLIs and integrations that do not return a usage percentage.
• Supports custom CLI probes whose output contains a percentage used.
• Runs commands without a shell, with bounded output and timeouts. The Cursor integration is the exception: it uses a temporary PTY through GNU script because Cursor exposes usage in its interactive /usage screen.

Supported integrations

CLI	Usage source	Requirement
Codex	account/rateLimits/read from codex app-server	An installed and authenticated codex CLI
Cursor Agent	The interactive /usage screen	An installed and authenticated cursor-agent CLI on a host with GNU script
Custom CLI	The first 0%–100% value printed by usageArgs	A command that reports percentage used

Unavailable integrations are omitted from the bar. Hover a visible percentage to see the provider label, usage window, and raw used/remaining context.

Install

Install the latest compatible tagged release from GitHub:

bb plugin install git:https://github.com/xtawfik/bb-plugin-cli-usage-bar.git@^0.1.0

BB asks you to confirm the source before installing third-party code. Git installs require npm on the connected host.

To install a development checkout instead:

git clone https://github.com/xtawfik/bb-plugin-cli-usage-bar.git
cd bb-plugin-cli-usage-bar
npm install
bb plugin install .

Configure

Open Settings → Plugins → CLI Usage Bar → Sidebar display. The clients setting accepts a JSON array with up to eight entries:

[
  {
    "id": "my-cli",
    "label": "My CLI",
    "command": "my-cli",
    "versionArgs": ["--version"],
    "usageArgs": ["usage"],
    "icon": "M"
  }
]

The command is considered installed when versionArgs starts successfully. usageArgs must print a percentage used such as 42%; the bar displays 58% remaining. Commands receive arguments directly rather than through a shell.

Codex and Cursor use dedicated probes when their executable names are codex/codex.js and cursor-agent/agent, so their usageArgs may remain empty.

How it works

The frontend registers a BB sidebar-footer disclosure. Its RPC handler selects the connected host, and the plugin's trusted host worker invokes each configured CLI. Results are schema-validated before the frontend displays them.

The plugin does not read or store API keys. It invokes CLIs that are already authenticated on the selected host. Usage percentages and short status text are returned to BB for display; no command output is persisted by the plugin.

Development

Requirements: Node.js 22, npm, and BB 0.42 or newer.

npm install
npm run typecheck
npm test
npm run build

For live development:

bb plugin install .
bb plugin dev

Before opening a pull request, run the complete local check:

npm run check

Marketplace readiness

The package includes BB engine constraints, public-SDK checks, a CI workflow, an Activity marketplace icon, and a marketplace-compatible PLUGIN_OVERVIEW.md. Releases use immutable vX.Y.Z Git tags so a BB Community marketplace entry can track a semver range.

License

MIT © 2026 Mohamed Tawfik.