Add salemsayed/codexbar-meter (#243)

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>
2026-08-05 17:57:32 -04:00
parent bffb68c86f
commit 1a08a98c4e
6 changed files with 1115 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 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.