AI Usage Bar — KDE Plasma 6 applet

A panel widget for ai-usagebar: it shows how much of your AI subscription quota (Claude, Codex, Z.AI, OpenRouter, Cursor, …) is left, without leaving the desktop.

ai-usagebar ships frontends for Waybar, GNOME Shell, Omarchy and macOS, but nothing for Plasma — and org.kde.plasma.commandoutput is not packaged on every distribution. This is that missing frontend, written as a regular KPackage applet.

What you get

• Panel text straight from ai-usagebar --json, colored by the binary (--icon and --format still apply).
• Tooltip: the card of the provider currently in the panel.
• Popup: one card per provider — usage bar per quota window, a marker at the elapsed position of the window, pacing hints, and a live countdown to the reset (computed from the absolute reset timestamp, so it keeps ticking between refreshes).
• Provider switching with the mouse wheel, the popup buttons, a click on a card, or the context menu. Providers without credentials are skipped instead of putting a ⚠ in the panel.
• Follows the color scheme (light and dark) and ships a Brazilian Portuguese translation.

Requirements

• KDE Plasma 6 (Qt 6)
• ai-usagebar in PATH (~/.local/bin and ~/.cargo/bin are searched as well), already logged in / configured for the providers you care about

Install

From a clone:

make install     # kpackagetool6 --install package
# or, over an existing install:
make upgrade

Then right-click the panel → Add Widgets… → AI Usage Bar.

To build the archive for the KDE Store or a manual install:

make plasmoid    # writes com.akitaonrails.aiusagebar.plasmoid

Uninstall with make uninstall.

Using it

Action	Result
Hover	Tooltip with the current provider's card
Left click	Popup with every configured provider
Middle click	Refresh now
Wheel	Previous / next provider
Click a card	Make that provider the panel's provider
Right click	Refresh, next/previous provider

Settings

Setting	Default	What it does
Binary path	ai-usagebar from PATH	Absolute path, if you keep it elsewhere
Interval	60 s	How often the panel text is refreshed
Provider	(cycled)	Pins one provider and disables switching
Extra arguments	—	Passed verbatim, e.g. --icon 󰚩 --format '{session_pct}%'
Mouse wheel	on	Whether the wheel switches provider
Without credentials	hidden	Hide such providers in the popup and skip them when switching

The provider currently on display is stored in the applet's own configuration (activeVendor), so switching does not disturb the vendor state shared by the binary's other frontends.

How it talks to the binary

The applet is deliberately thin — fetching, credentials, product names, metric projection and reset metadata all stay in ai-usagebar:

Command	Used for
ai-usagebar [--vendor X] [extra args] --json	Panel text (Pango markup converted to Qt rich text)
ai-usagebar usage --json	Tooltip and popup cards
ai-usagebar settings show	The default provider, once, at first start

usage and settings are subcommands: the binary's argument parser rejects --vendor (and the other global options) next to them, so those command lines are built separately from the panel one.

All provider-controlled text is sanitized in Model.js (control characters, bidi overrides, length bounds) and rendered as Text.PlainText; the only rich text is the panel string, whose Pango spans are translated attribute by attribute and whose remaining markup is escaped.

Translations

The catalog domain is plasma_applet_com.akitaonrails.aiusagebar, loaded from package/contents/locale/<lang>/LC_MESSAGES/. pt_BR ships with the applet.

./po/extract.sh                 # refresh po/*.pot and merge into the catalogs
cp po/plasma_applet_*.pot po/<lang>.po   # start a new language
make catalogs                   # compile every po/*.po into the package

Development

make test     # node contract tests for the pure model (no Qt needed)
make lint     # qmllint over the QML sources
make run      # plasmawindowed, no panel involved

make test covers the report contract: JSON normalization, provider cycling, duration formatting, detail parsing, the Pango conversion, and that every plasmoid.configuration.* key the QML reads exists in main.xml.

Restart the shell after installing a change: kquitapp6 plasmashell && plasmashell &.

Credits

• ai-usagebar by Fabio Akita — this applet is only a frontend for it.
• Applet: Marcelo <Marcelo7889@gmail.com>, MIT licensed (same as upstream).