1a08a98c4e
A bar widget and attached panel showing AI provider usage limits reported by the local CodexBar CLI. The bar keeps a configurable number of provider meters; the panel lists every provider, quota window, credit balance, and pace summary, and scrolls when the response is taller than the panel. Claude-Session: https://claude.ai/code/session_01BCNAY79YEoNxyubdt8Co9A Co-authored-by: Salem Sayed Abdel Gawad <283208+salemsayed@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# CodexBar Meter
|
||
|
||
CodexBar Meter is a native Noctalia v5 bar widget and attached panel for usage
|
||
limits reported by the local [CodexBar](https://github.com/steipete/CodexBar)
|
||
CLI. It discovers the providers enabled in CodexBar, keeps the bar compact,
|
||
and exposes every provider and quota window in a scrollable panel.
|
||
|
||
## Plugin
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| ID | `salemsayed/codexbar-meter` |
|
||
| Entries | Bar widget: `bar`; panel entries: `panel-compact`, `panel`, `panel-tall` |
|
||
|
||
## Requirements
|
||
|
||
Install these commands on `PATH`:
|
||
|
||
- `codexbar` 0.47 or newer, configured with at least one provider.
|
||
- `timeout` from GNU coreutils.
|
||
|
||
CodexBar owns provider authentication, network access, and provider discovery.
|
||
The plugin does not read or store provider credentials.
|
||
|
||
## Usage
|
||
|
||
Add `salemsayed/codexbar-meter:bar` to a Noctalia bar. The bar shows up to two
|
||
provider meters by default, followed by a `+N` count when more providers are
|
||
enabled in CodexBar. The tooltip includes all returned providers.
|
||
|
||
- Left-click opens the attached `CodexBar Meter` panel. The widget chooses a
|
||
compact, standard, or tall panel tier from the current provider payload;
|
||
each tier keeps scrolling as the safety net for unusually large responses.
|
||
- Right-click refreshes usage immediately.
|
||
- The panel refresh button requests a fresh CodexBar query.
|
||
- The panel close button dismisses the panel.
|
||
|
||
To open the standard panel from a terminal:
|
||
|
||
```sh
|
||
noctalia msg panel-toggle salemsayed/codexbar-meter:panel
|
||
```
|
||
|
||
The adaptive widget also uses these panel entries when opening from the bar:
|
||
|
||
- `noctalia msg panel-toggle salemsayed/codexbar-meter:panel-compact` — 390 px
|
||
- `noctalia msg panel-toggle salemsayed/codexbar-meter:panel` — 560 px
|
||
- `noctalia msg panel-toggle salemsayed/codexbar-meter:panel-tall` — 720 px
|
||
|
||
The panel renders all provider cards and scrolls when the response is taller
|
||
than the panel. It understands CodexBar's standard primary, secondary, and
|
||
tertiary windows, named `windows` and `extraRateWindows`, credits, pace
|
||
summaries, provider status, stale data, and per-provider errors. Unknown
|
||
providers receive a readable title, a neutral icon, and a theme-derived color.
|
||
|
||
## Settings
|
||
|
||
| Setting | Type | Default | Description |
|
||
| --- | --- | --- | --- |
|
||
| `codexbarPath` | `string` | `codexbar` | Command or absolute path used to query CodexBar. |
|
||
| `refreshIntervalSec` | `int` | `60` | Background refresh interval in seconds; allowed range is 30–3600. |
|
||
| `barProviderLimit` | `int` | `2` | Number of provider meters shown in the bar; allowed range is 1–4. The panel and tooltip always include all providers. |
|
||
|
||
When no provider flag is supplied, CodexBar's configured enabled-provider list
|
||
is used. This lets the plugin work with any current or future CodexBar
|
||
provider without changing the Noctalia code.
|
||
|
||
## IPC
|
||
|
||
Refresh the widget and panel through the shared plugin state:
|
||
|
||
```sh
|
||
noctalia msg plugin salemsayed/codexbar-meter:bar all refresh
|
||
```
|
||
|
||
## Notes
|
||
|
||
- The plugin runs `timeout 30s <codexbarPath> usage --format json --json-only`.
|
||
- A provider-level error is kept as a card beside healthy providers. If a
|
||
refresh returns no usable JSON, the last successful response remains visible
|
||
with an explicit warning.
|
||
- The plugin is compositor-agnostic: it uses Noctalia's attached layer-shell
|
||
panels and theme roles rather than hard-coded light or dark colors, and calls
|
||
no compositor IPC of its own. Developed on Niri.
|
||
- The plugin writes no files and opens no network connections of its own. The
|
||
panel displays the account identity CodexBar reports for a provider, such as
|
||
the signed-in email address. CodexBar itself owns provider authentication,
|
||
credential storage, and all network access.
|