README.md

CodexBar Plasma

KDE Plasma 6 widget for CodexBar.

This repository is intentionally small: it contains only the Plasma applet. All provider logic, authentication, configuration, quota parsing, and JSON output come from the codexbar CLI.

CodexBar Plasma overview

Codex provider detail

Features

Multi-provider Plasma panel indicator.
Provider tabs with usage bars, reset windows, credits, local token cost, and provider status links.
Local cost drill-down with token breakdowns, model summaries, recent daily spend, cost history bars, and average cost per 1M tokens where the CLI exposes those fields.
Provider settings page for enable/disable, API key setup, docs, dashboards, login/account links, redacted provider diagnostics, and provider-specific CLI command hints.
Split settings pages for general refresh/notification controls, display, advanced provider overrides, about links, and redacted CLI diagnostics.
Optional compact multi-provider panel meters.
Display mode controls: Percent, Pace, Percent and pace, Reset time.
Refresh presets: Manual, 1 min, 2 min, 5 min, 15 min, or custom seconds.
Auto-select highest-usage provider for the compact panel and provider detail focus.
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 and 80/95% quota crossings.
Optional Plasma notifications when a heavily used limit resets back to empty.
Account discovery and selection through codexbar usage --all-accounts.

Requirements

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

On Arch-compatible systems:

1	yay -S codexbar-cli

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

Install

From the repository root:

1	kpackagetool6 -t Plasma/Applet -i .

Then add CodexBar to a Plasma panel.

Upgrade

1	kpackagetool6 -t Plasma/Applet -u .
2	systemctl --user restart plasma-plasmashell.service

CLI Check

Before debugging the widget, verify the data source directly:

1	codexbar usage --format json --json-only
2	codexbar usage --format json --json-only --provider codex --source oauth
3	codexbar usage --provider codex --all-accounts --format json --json-only
4	codexbar cost --format json --json-only

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:

text

1	/usr/bin/codexbar

Test

1	scripts/test_feature_parity.sh
2	scripts/test_refresh_nonce.sh
3	scripts/test_provider_icons.sh
4	scripts/test_security_regressions.sh
5	scripts/test_qml_hardening.sh
6	/usr/lib/qt6/bin/qmllint --unqualified disable -I /usr/lib/qt6/qml contents/ui/main.qml contents/ui/configGeneral.qml contents/ui/configProviders.qml contents/ui/configDisplay.qml contents/ui/configAdvanced.qml contents/ui/configAbout.qml contents/ui/configDebug.qml
7	xmllint --noout contents/config/main.xml
8	jq . metadata.json >/dev/null
9	kpackagetool6 --appstream-metainfo . \| xmllint --noout -

make check runs qmllint with --unqualified disable because Plasma injects helpers such as i18n() as context properties that otherwise create noisy false-positive warnings.

Structure