Add OpenCodexBar plugin

[wy3z]

Plugin

• Id: wy3z/opencodex-bar
• New plugin
• Update to an existing plugin (version bumped in plugin.toml)

What it does

I wanted a quick way to keep an eye on my local OpenCodex instance without opening its dashboard all the time, so I put together OpenCodexBar.

It adds a small bar indicator and an attached panel with two views:

• Accounts shows each account’s OpenCodex-reported subscription plan, health, quota windows, reset times, and Codex reset credits. It can also select the account OpenCodex should use for the next turn and consume an available reset credit, with confirmation before either action.
• Usage shows today's requests and tokens, a 30-day activity grid, provider/model totals, and estimated cost.

There is already a CodexBar-based meter in the marketplace, but this one is aimed at people running OpenCodex. It talks to OpenCodex's Management API directly instead of installing or calling the CodexBar CLI, so the panel reflects the accounts and providers from the OpenCodex instance you already have running. It also goes a bit further than the quota view: you can jump straight to the OpenCodex control panel, see today's requests, tokens, and estimated cost, browse a 30-day activity grid, and break usage down by provider and model.

There is a small service behind both views. It is the only part that handles the Management API credential; the widget and panel only exchange normalized snapshot, command, and action state, with the credential removed. Account selection and reset-credit use are validated against the latest snapshot, confirmed in the panel, and followed by a forced quota refresh.

External dependencies

• OpenCodex 2.31.0: polling uses authenticated GET requests. Confirmed account actions use PUT /api/codex-auth/active and POST /api/codex-auth/reset-credits/consume.
• Admin token: read from OPENCODEX_ADMIN_AUTH_TOKEN, or from the configured admin_token_file if the environment variable is unavailable. The plugin writes no local files; confirmed account actions mutate OpenCodex state.
• xdg-open: used by the link button to open the OpenCodex dashboard. It is called with an argument array rather than through a shell, and nothing else is spawned.

As a small safety guard, plain HTTP is only allowed for loopback addresses. Anything remote has to use HTTPS.

Testing

I tested this against my live OpenCodex 2.31.0 setup on Hyprland:

• Loaded the usage, panel, and service entries and checked that the bar widget rendered.
• Opened and closed the panel both from the widget and with noctalia msg panel-toggle wy3z/opencodex-bar:panel.
• Checked the Accounts and Usage tabs, normal and forced refreshes, quota/reset data, the activity grid, provider/model totals, estimated cost, and dashboard URL handling.
• Tested OAuth, API-key, forwarded, disabled, and hidden providers.
• Added coverage for token-file rotation, environment-token precedence, invalid URLs, auth failures, control characters in credentials, stale callbacks, watchdog recovery, active-account selection, reset-credit consumption, and invalid-account rejection.

Automated checks:

• lua tests/test_service.lua — 12 tests, 0 failures

• noctalia plugins lint — 0 errors, 0 warnings

• Current community validator — passed

• Tested on Niri

• Tested on Hyprland

• Tested on Sway

• Tested on another compositor:

• Noctalia version tested against: v5.0.0

• Plugin API level: 24

Screenshots / Videos

Accounts

Usage

Checklist

Ready-for-review requirement: Every box in this section must be checked. If any statement is not true, keep the
pull request as Draft. An explanation does not replace a required check.

• The directory name matches the part of id after the / in plugin.toml exactly.
• It ships plugin.toml, README.md, thumbnail.webp, and translations/en.json.
• README.md follows the
  README template, documents
  every entry id and dependency, and includes exact panel IPC commands and launcher prefixes where applicable.
• I created thumbnail.webp with the thumbnail generator.
• version follows semver and is bumped in this PR; plugin_api is the oldest API level this plugin requires.
• Every non-English translation in this PR uses a locale supported by Noctalia core, and I can read, write, and
  understand that language well enough to review and maintain it (no unreviewed machine/LLM translations).
• I did not edit catalog.toml; CI generates it.
• This PR touches exactly one plugin directory.

Code review attestation

Plugins run as trusted, unsandboxed Luau in the user's session. Confirm:
Ready-for-review requirement: Every attestation below must be checked.

• The code is readable and not obfuscated, minified, or generated.
• It does not download and execute remote code.
• Every network call, filesystem write, and spawned process is something the description above accounts for.
• I have the right to publish this code under the license declared in plugin.toml.