CodexBar Plasma

Track Codex, Claude, Gemini, and 90+ more AI providers from your KDE Plasma 6 panel. Quotas, reset windows, costs, local agent sessions, notifications, and multiple accounts per provider.

Install · Features · Troubleshooting · Development

The current popup in Breeze Dark with synthetic data. The widget follows your Plasma theme; provider accent colors stay consistent across themes.

Install

Quick install from a terminal

From a terminal in your Plasma 6 desktop session, run this as your regular user, without sudo. Bash must be installed; your terminal can use another shell.

This runs a small bootstrap from this repository's main branch. It downloads the complete installer before running it and keeps prompts in your terminal. It installs the latest stable release package for your user, with no Git checkout or build. It reports missing command-line dependencies before downloading the package. The runtime requirements still apply.

1. If codexbar is absent from your terminal's PATH, setup offers to install or reuse a private official CLI. Answer y to prepare it now.
2. Add CodexBar to your panel through Add Widgets. If you prepared the private CLI, open the widget settings, select General → Managed CLI → Use managed CLI, and click Apply. This selection is required even after the terminal reports that the private CLI is ready.
3. Enable and configure your providers in the widget's Providers settings.

Existing CLI installations and provider credentials are preserved. Rerunning the command upgrades an older widget and offers to restart Plasma. Prompts default to No; without a terminal they are skipped.

KDE Store or manual installation

1. Install the Linux CLI from the official CodexBar release tarballs or another method documented by upstream CodexBar. Third-party packages such as AUR can lag behind upstream releases. Alternatively, install the widget first and use General → Managed CLI → Install and select managed CLI, then Apply. This downloads an official Linux binary to a private directory without replacing a system installation. If the CLI is missing, the popup shows this setup route even after switching to Usage & Spend or Sessions. Use the resolved path from Diagnostics → Check versions for terminal commands. Set up your provider using the upstream instructions, then verify usage:

   sh

   1	codexbar usage --format json --json-only

2. Install the widget. From your panel, open Add Widgets → Get New Widgets → Download New Plasma Widgets, search for CodexBar, and install it from the KDE Store.

   Or download codexbar-plasma.plasmoid from the widget's latest release and run, in the directory containing that file:

   sh

   1	kpackagetool6 -t Plasma/Applet -i codexbar-plasma.plasmoid

   The GitHub release is the newest package; a store listing can trail it. The widget's own update check always follows GitHub releases.

3. Open your Plasma panel's Add Widgets chooser and add CodexBar.

4. Open the widget settings. Use Providers to enable providers and supported setup actions, Panel to adjust the compact display, and General to choose refresh and privacy settings.

Provider enable/disable and setup actions change the CLI configuration immediately. Apply and Cancel cover widget settings only.

New widgets refresh quotas every five minutes, refresh again when you open the popup on quotas older than that interval, and show percent used. Warning and critical thresholds default to 80% and 95%. Existing settings are preserved when you upgrade.

Failed refreshes retain quotas measured within the last 24 hours and identify them as last known. A redacted cache restores recent quotas after a Plasma restart while the CLI refreshes. See data freshness for its limits.

Requirements

• KDE Plasma 6, kpackagetool6, and the org.kde.plasma.plasma5support QML module.
• QtQuick.Dialogs and KDE Declarative's org.kde.kquickcontrolsaddons QML modules for the local usage-sharing window, file picker, and image clipboard.
• A working codexbar CLI, available on Plasma's PATH or through an absolute path configured in the widget, including its optional managed copy. Managed downloads support Linux x86_64/aarch64 with glibc or musl; the downloaded executable must pass a local version probe before activation.
• notify-send for Plasma notifications.
• Offline Diagnostics support-report collection: python3 and GNU timeout. Other Diagnostics controls remain available without this report helper.
• Optional AI Insights only: python3 and GNU timeout; for OpenRouter or OpenAI keys also kdialog, secret-tool, and a Secret Service provider such as KWallet. Nothing is required while the feature is off.
• Optional identified Codex token subtotals: codexbar 0.75.0 or later and GNU timeout. Including an SSH source also requires that CLI on the remote computer and working noninteractive SSH authentication with trusted host keys.
• curl, jq, python3, sha256sum, GNU timeout, and util-linux flock for the bundled release updater. CLI release checks and managed installs also use python3 and GNU timeout. GNU timeout also bounds CLI writes after a secret prompt.

Distribution package names vary. Source builds also need make, Python 3, and GNU gettext; see Development.

Features

Collect an offline support report in Diagnostics, review its preview, and copy it into a bug report. It includes installed versions, selected/system CLI paths and ownership, enabled provider IDs and module checks, with home usernames and credentials redacted.

Share a local usage summary from Usage & Spend as a PNG or copied text. The preview includes the selected history range, token totals, estimated usage costs, providers, and top models, with a small repository attribution. See usage sharing.

Standard panel	Minimal panel

The same Codex, Claude, and Gemini usage in both styles. Small provider icons sit beside primary and secondary quota capsules. Choose the appearance in Panel settings. These examples show meters with panel text hidden.

Provider overview	Local sessions
Usage & Spend	Provider details

The popup captures are the full-size stills behind the animation above. Click an image to open it. Panel captures show the capsule design released in 0.2.36; popup captures show the current popup. All use Breeze Dark with synthetic data. The widget follows your Plasma theme; provider accent colors stay consistent across themes.

• Quota meters, reset windows, account selection, and provider status in the panel and popup, with configurable quota warnings and Plasma notifications.
• Standard and Minimal panel styles with up to two quota capsules per provider, horizontal and vertical meters, selectable quota windows, conditional text and meters, and a live settings preview that stays visible while scrolling. Optional text sits beside the selected provider's capsules with the default order. Panel settings keep appearance and meters visible; additional information and quota/order/visibility options expand when needed.
• Usage & Spend with cost/token charts, a 7/30/90-day, month-to-date, or all-history range, an activity heatmap, and provider, model, and project breakdowns when the CLI supplies them.
• An optional manual Codex identified-request token subtotal, with separate local and local + SSH actions, an independent UTC window, and partial-data notices. It is off by default and has no prices or account-wide coverage.
• A local Sessions tab. Transcript paths and working directories are never displayed or opened.
• Refresh on popup opening, plus optional privacy mode and automatic widget updates.
• Optional, off-by-default beta AI Insights: a short summary in Overview with an in-popup analysis view, from a local Ollama model, OpenRouter, or OpenAI, written in the widget's interface language from aggregated statistics only.
• English plus Italian, French, German, Spanish, and Brazilian Portuguese, selected through your Plasma language preferences.

Provider authentication and data support come from the CLI. The widget includes per-provider source selection in Providers → Settings and diagnostics with CLI 0.73.0 or later; the source override in Diagnostics takes precedence. It also includes fallback metadata for all 106 providers in the official CodexBar 0.77.0 registry, covering names, icons, and documentation links, with brand colors and dashboard and status links where upstream defines them. Available metrics and setup actions vary by provider. Command Code and fal offer single API-key setup with CLI 0.75.0 or later, and Munito with CLI 0.77.0 or later. Future AGI setup requires a secret-key writer that the official Linux CLI does not yet provide. The proposed generic provider-settings descriptor is not available in CLI 0.77.0; its additional editors remain unavailable.

See the usage and settings guide for options and defaults, the documentation index for verified CLI evidence, and Linux parity TODO for remaining Linux/Plasma work.

Update

Read the changelog for changes and upgrade notes by version.

To upgrade a release installation, download the new .plasmoid and run:

Log out and back in to load the new widget code, or reload your Plasma panels and desktop with:

In General → Updates, Check for widget updates and update notifications are enabled by default. Checks run every 24 hours by default; restarting Plasma respects the last successful check, while first use or an overdue check runs immediately. Manual checks bypass the interval. Clicking an update notification opens that release's page on GitHub where the installed notify-send supports notification actions. Install widget updates automatically is opt-in.

The widget-update helper accepts only immutable GitHub releases. It binds assets to the advertised tag, verifies SHA-256 digests and the published checksum, and checks the applet ID and version before installation. A validation mismatch aborts the update. Before upgrading, the helper backs up the installed widget and restores it if installation fails or the installed metadata is invalid.

General → CLI updates offers a manual check of official CodexBar releases and optional daily checks, off by default. Notifications can be enabled separately. These announce upstream releases, not package-manager availability. AUR and other package users should update through their existing package tools; the widget never replaces their CLI. Recognized ownership includes pacman, dpkg, RPM, APK, and Homebrew. Unrecognized installations keep their original update method. Diagnostics → Check versions stays offline and reports the installed CLI, resolved command, and recognized installation manager.

General → Managed CLI can install and select a separate private CLI, update it immediately, or restore its previous version. An existing managed copy can be selected offline with Use managed CLI. Before a first install, an offline probe identifies the selected CLI so a working external copy receives a confirmation without needing a GitHub release check. If the probe cannot identify the CLI, installation waits until Retry succeeds or the selected command is confirmed missing. Automatically update the managed CLI daily is optional and off by default; it acts only while the managed command path is selected. Downloads match the host architecture/libc, verify GitHub SHA-256 metadata and the published checksum, accept only bounded expected archive entries (including the optional third-party notice), and switch atomically after a version probe. A restored version stays selected until a newer release arrives or you explicitly update again. See managed CLI details.

For a source checkout, see the development update commands. The source-checkout helper ./install.sh checks for kpackagetool6 and systemctl before building, then installs the package and restarts Plasma.

Troubleshooting

The widget stays on Loading or cannot find the CLI

Usage errors in the popup offer Retry and Settings. Open Diagnostics in widget settings to check the connection. Retry is unavailable while a quota refresh is running; the last known quotas stay visible when available.

If the popup says CodexBar CLI not found, Plasma could not run the configured command at all, so there is nothing to retry. Set an absolute path as described below. Diagnostics → Check versions reports the widget and CLI versions and the absolute command the shell resolved.

Run codexbar usage --format json --json-only in a terminal. If it fails, resolve the provider or CLI setup first. If it works, locate the executable:

Paste the returned absolute path into Diagnostics → Command path. Plasma may have a different PATH from your terminal. Use PATH restores the portable codexbar default.

Providers, accounts, or costs are missing

If the popup has no provider data, choose Configure providers, then open Providers in widget settings to enable or set up a provider.

Check that the provider is enabled in Providers, then inspect the relevant CLI response. For example, for Codex accounts and local cost data:

The widget can display only data the CLI returns. Cost availability varies by provider; missing dollar amounts do not mean zero spend. If a feature is absent, check the usage guide and Linux parity TODO.

Notifications do not appear

Check the widget's Notifications settings and test desktop notifications:

Report a problem

Open a widget issue and complete the form: reproduction steps, expected and actual behavior, your distribution, and the Plasma, widget, and CLI versions. Report a suspected vulnerability privately through the security policy instead of opening an issue. For QML errors, inspect recent logs:

Include only relevant CodexBar errors. Redact account details, paths, credentials, and other personal information before sharing logs or screenshots. If the CLI command itself fails, consult upstream CodexBar for provider setup and CLI support.

Development

Build and install from a checkout:

Then reload Plasma as described under Update. Run make check before submitting changes. The development guide covers dependencies, checks, isolated popup smoke tests, packaging, and QML conventions. See the documentation index for maintained references.

Contributions to the Plasma widget are welcome through pull requests. Read CONTRIBUTING.md first and include the verification results requested by the PR template. Provider logic and CLI contracts belong upstream. To add or improve a language, follow the translation guide. CLI-supplied free-form text retains its original language.

Support

If CodexBar Plasma saves you time, you can support development on Ko-fi. The same link is in the repository's Sponsor button.

License and attribution

CodexBar Plasma is a standalone frontend for the official CodexBar CLI. The widget code is distributed under the MIT License. Bundled provider artwork includes upstream CodexBar assets and a Poe icon under CC BY 4.0. See NOTICE.md for sources, licenses, and attribution.