CodexBar Usage for Noctalia

A Noctalia v5 plugin that presents CodexBar provider usage as a compact bar widget with native usage and settings panels. Its layout follows CodexBar's macOS menu: a selectable provider strip at the top, one active provider below it, thin branded quota bars, percentage and reset labels, pace, credits, and extra-usage sections.

Requirements

• Noctalia 5.0.0 or newer
• A working codexbar CLI
• At least one provider configured in CodexBar

The background service asks CodexBar for JSON and shares only normalized display data with the widget and panel. Last successful provider cards stay in shared plugin state and remain visible during background refreshes. Newly enabled providers appear immediately with their own loading body. For GitHub Copilot, the plugin reuses the active GitHub CLI account without displaying or persisting its token. The settings panel also lets you choose any number of enabled providers for the bar; their compact icon and short quota gauge appear consecutively, while an empty selection produces a logo-only widget.

Install

Add the repository as a Git plugin source, enable the plugin, and then add the CodexBar Usage widget from Noctalia's widget picker:

noctalia msg plugins source add codexbar git https://github.com/xikhar/codexbar-noctalia
noctalia msg plugins enable xikhar/codexbar

Update the installed source with:

noctalia msg plugins update codexbar

If Noctalia cannot find codexbar, open the plugin settings and set CodexBar executable to its absolute path. This is common when the shell is launched from a graphical session with a smaller PATH.

Open the panel directly during development with:

noctalia msg panel-toggle xikhar/codexbar:details

Open its configuration panel with:

noctalia msg panel-toggle xikhar/codexbar:settings

Local development

Add this checkout as a path source. Local .luau edits hot-reload, while manifest changes are picked up after a Noctalia configuration reload:

noctalia msg plugins source add codexbar-dev path "$HOME/Projects/codexbar-noctalia"
noctalia msg plugins enable xikhar/codexbar
noctalia msg plugins update codexbar-dev

Validate

noctalia plugins lint .

The repository is shaped as a Noctalia plugin source: catalog.toml indexes the plugin, while all distributable files live under codexbar/.

For editor completion, fetch Noctalia's current API declaration into the repository root. It is intentionally gitignored so the official plugin repo remains its single source of truth:

curl -O https://raw.githubusercontent.com/noctalia-dev/official-plugins/main/noctalia.d.luau

If this plugin is submitted to noctalia-dev/community-plugins, copy only the codexbar/ directory. That repository generates its own catalog.toml in CI.

Backend modes

• Command (default) runs codexbar usage --format json --json-only at the configured interval with a configurable command timeout and no provider override, so CodexBar follows its enabled-provider configuration. Provider toggles in the plugin settings panel update that configuration through the CLI. Source, status, and executable settings are forwarded as CLI arguments.
• HTTP server queries the /usage endpoint of an already running codexbar serve instance. The plugin does not start or supervise that server.

The service keeps each provider's last successful result in shared plugin state. Refreshes retain those cards and the provider strip while new data is fetched; providers without cached data receive an individual loading body. Failed refreshes preserve the cached display while keeping the relevant errors visible.

Project layout

codexbar/
  plugin.toml             Plugin manifest and settings
  service.luau            CodexBar adapter and shared-state publisher
  widget.luau             Compact bar presentation
  panel.luau              CodexBar-style details panel
  settings.luau           General and provider configuration panel
  assets/                 Provider icons adapted from CodexBar
  translations/en.json    English UI strings

Credits and license

The plugin is MIT licensed. The provider-card visual reference and provider icons are adapted from CodexBar, also under the MIT License. See codexbar/THIRD_PARTY_NOTICES.md.