CodexBar Plasma

KDE Plasma 6 widget for CodexBar. It shows AI provider usage, reset windows, costs, status, and account data in the Plasma panel.

This repository contains only the Plasma applet. Provider logic, authentication, configuration, quota parsing, and JSON output come from the codexbar CLI.

Screenshots use one Plasma theme and accent color. The widget follows the user's Plasma theme for text, surfaces, selection, and status colors; provider accent colors stay stable for recognition.

Install

1. Install the codexbar CLI.

   On Arch-compatible systems:

   sh

   1	yay -S codexbar-cli

   You can also install the CLI from the main CodexBar release tarballs or from a local Swift build.

2. Download codexbar-plasma.plasmoid from the latest release.

3. Install the widget:

   sh

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

4. Add CodexBar to a Plasma panel.

To upgrade an existing install:

To update from a local checkout or GitHub Release asset helper:

The widget can also check GitHub Releases for newer .plasmoid packages. Check for widget updates and update-available notifications are enabled by default; Install widget updates automatically is opt-in. If the widget is published through KDE Store in the future, prefer Plasma Discover/KNewStuff for that install channel.

Requirements

• KDE Plasma 6
• kpackagetool6
• org.kde.plasma.plasma5support
• codexbar CLI on PATH, or an absolute CLI path configured in the widget
• notify-send for optional Plasma notifications

If Plasma does not inherit your shell PATH, set an absolute command path in the widget settings. On Arch/CachyOS with the AUR package this is usually:

CLI Check

Before debugging the widget, verify the data source directly. If these commands do not work, the Plasma widget cannot show the corresponding data.

Features

Panel and popup:

• Compact panel indicator for one provider or multiple providers.
• Provider tabs with usage bars, reset windows, account identity, status, and credits.
• Display modes for percent used, pace, percent plus pace, and reset time.
• Auto-select highest-usage provider for the compact panel and provider detail focus.
• Usage dashboard summaries for provider payloads that expose API spend, request, token, model, or dashboard fields through the CLI.

Providers and accounts:

• Provider enable/disable controls.
• Account discovery and selection through codexbar usage --all-accounts.
• Provider docs, dashboards, login/account links, and redacted diagnostics.
• Provider-specific CLI command hints.

Costs and history:

• Local cost drill-down when the CLI exposes cost data.
• Token breakdowns, model summaries, recent daily spend, cost history bars, and average cost per 1M tokens, with a configurable cost history window.

Status and notifications:

• Provider status incident badge in the panel and provider detail view.
• Optional quota warning markers on usage bars.
• Optional Plasma notifications for provider status incidents, 80/95% quota crossings, and when a heavily used limit resets back to empty.

Settings:

• Split settings pages for general refresh/notification controls, display, advanced provider overrides, and redacted CLI diagnostics.
• Refresh presets: Manual, 1 min, 2 min, 5 min, 15 min, or custom seconds.
• Check for widget updates, notify when an update is available, and opt in to silent automatic widget installation.

Troubleshooting

If the widget stays on Loading:

If that works in a terminal but not in Plasma, set the widget command path to the absolute CLI path, for example /usr/bin/codexbar.

If providers or accounts are missing:

Then check the Providers settings page and make sure the provider is enabled.

If costs are missing:

Cost sections are shown only when the CLI returns cost data for the selected provider.

If notifications do not appear:

Then confirm notifications are enabled in the widget settings.

For Plasma/QML errors:

Development

Install from a local checkout:

Upgrade a local checkout:

Run checks:

Package locally:

make check runs the static shell checks, XML/JSON checks, and qmllint with --unqualified disable because Plasma injects helpers such as i18n() as context properties that otherwise create noisy false-positive warnings.

Project structure:

Provider support stays upstream in CodexBar. When the Plasma frontend needs new data, add it to the CLI JSON contract first instead of scraping or editing CodexBar config files directly from QML.

Attribution

CodexBar Plasma is derived from the CodexBar project and uses the same MIT license. See NOTICE.md.