CodexBar for KDE Plasma 6

Your AI coding limits, always visible in the panel.

A faithful KDE Plasma port of CodexBar, Peter Steinberger's macOS menu bar app. Codex, Claude, Cursor, Copilot, Gemini and 60+ more providers, driven by the official CodexBar CLI.

⚡ Install in one line

curl -fsSL https://raw.githubusercontent.com/psimaker/codexbar-plasmoid/main/scripts/install.sh | sh

Then right-click your panel → Add Widgets… → search CodexBar. That's it.

	What the one-liner does
🧩 Widget	Downloads the latest .plasmoid release, verifies its SHA-256 checksum and installs it with kpackagetool6.
🖥️ CLI	Downloads the official CodexBar CLI build for your CPU (x86_64 / aarch64), verifies the checksum and links it as ~/.local/bin/codexbar.
🔒 Safe	User-local only, no root, nothing outside ~/.local. Re-run it any time to update both.

Tip

Already have the widget? It installs and updates the CLI by itself: the popup shows an Install CodexBar CLI button when the CLI is missing or too old, and About CodexBar offers Update CodexBar CLI to the latest release.

Options: --widget-only, --cli-only, --version v0.4.0. The scripts are plain POSIX sh, so read them first if you like: scripts/install.sh and contents/scripts/install-cli.sh. Manual and package-manager routes are below.

✨ Features

• Panel icon in the original look. Two meter capsules (session on top, weekly below), fill = remaining quota, dimmed when data is stale. One merged icon showing the worst case across providers by default, or one icon per provider with the original "critter" faces for Codex and Claude. Optional percentage label, or provider logos instead of meters.
• Popup like the original menu. Provider switcher tabs with brand-colored quota bars, an overview page, and per provider: session / weekly / extra rate windows ("Codex Spark", model-scoped weekly caps, …) with progress bars, reset countdowns and a pace line, Codex reset credits, local cost (today / last 30 days via codexbar cost), provider status, account info, and the CLI's detail rows (balances, monthly spend, credit pools, …).
• Actions. Refresh, cost-history refresh, Usage Dashboard, Status Page, Settings, About.
• 69 providers. Everything the CodexBar CLI supports, enable only what you use.
• Optional Claude multi-account view. Stacked 5-hour and 7-day cards per account with explicit switching through a schema-v1 claude-swap adapter.

  

All 69 supported providers

Codex · OpenAI · Azure OpenAI · Claude · ClinePass · Cursor · OpenCode · OpenCode Go · Alibaba Coding Plan · Alibaba Token Plan · Qwen Cloud · Droid · Fireworks · Gemini · Antigravity · Copilot · Devin · z.ai / GLM · MiniMax · Manus · Kimi Code · Kilo · Kiro · Vertex AI · Augment · JetBrains AI · Moonshot / Kimi API · Amp · T3 Chat · Ollama · Synthetic · OpenRouter · ElevenLabs · Warp · Windsurf · Zed · Perplexity · Xiaomi MiMo · Doubao · Sakana AI · Abacus AI · Mistral · DeepSeek · DeepInfra · Codebuff · Crof · Venice · Command Code · Qoder · StepFun · AWS Bedrock · Grok · Groq · LLM Proxy · LiteLLM · Deepgram · Poe · Chutes · Neuralwatt · ClawRouter · LongCat · sub2api · Wayfinder · ZenMux · ai& · ZoomMate · xAI · Notion AI · IBM Bob

Provider logins are handled by the provider tools themselves (Claude Code, Codex CLI, API keys in CodexBar's config, …); the widget only reads what the CLI reports. Some newer providers need a recent CLI, which the widget tells you when a probe fails.

📋 Requirements

• KDE Plasma 6 (kpackagetool6)
• CodexBar CLI 0.43.0 or newer, latest recommended. The one-liner and the widget install it for you; see other ways for Homebrew, AUR or a manual download.

The widget and the CLI are separate: the CLI is not bundled inside the .plasmoid, but the widget bundles an installer for it.

🛠️ Other ways to install

Widget from a .plasmoid file

1. Download the current .plasmoid file from GitHub Releases.
2. Right-click the Plasma panel or desktop and select Add Widgets….
3. Select Get New Widgets → Install Widget From Local File… and pick the downloaded file.
4. Search for CodexBar and add it to the panel.

From a terminal instead:

kpackagetool6 -t Plasma/Applet -i com.github.psimaker.codexbar-<version>.plasmoid   # install
kpackagetool6 -t Plasma/Applet -u com.github.psimaker.codexbar-<version>.plasmoid   # update
kpackagetool6 -t Plasma/Applet -r com.github.psimaker.codexbar                     # remove

Each release ships a .sha256 file. Download it next to the .plasmoid and verify before installing:

sha256sum -c com.github.psimaker.codexbar-<version>.plasmoid.sha256

An updated widget takes effect after Plasma reloads it (log out and in, or systemctl --user restart plasma-plasmashell.service).

A KDE Store listing is planned but not published yet; until then use the release package.

CodexBar CLI: widget button, Homebrew, AUR or manual download

The widget finds codexbar on PATH (including ~/.local/bin). Alternatively right-click the widget → Configure CodexBar… and set a custom CLI path.

• From the widget. Setup card → Install CodexBar CLI, or About page → Update CodexBar CLI to the latest release. Same installer as the one-liner: official release archive, checksum verified, user-local.

• Homebrew / Linuxbrew: brew install steipete/tap/codexbar

• Arch Linux (AUR): yay -S codexbar-cli

• Manual download. Get CodexBarCLI-v<tag>-linux-<arch>.tar.gz from the CodexBar releases (a static linux-musl build exists for systems with an older glibc). Extract the whole archive and keep CodexBarCLI, its VERSION file and the CodexBar_CodexBarCore.bundle directory together:

  mkdir -p ~/.local/share/codexbar-cli/<tag> ~/.local/bin
  tar -xzf CodexBarCLI-v<tag>-linux-<arch>.tar.gz -C ~/.local/share/codexbar-cli/<tag>
  ln -sfn ~/.local/share/codexbar-cli/<tag>/CodexBarCLI ~/.local/bin/codexbar
  ~/.local/bin/codexbar --version

From source (development)

git clone https://github.com/psimaker/codexbar-plasmoid.git
cd codexbar-plasmoid
kpackagetool6 -t Plasma/Applet -i .     # later: -u . to update
tests/run-tests.sh

scripts/build-plasmoid.sh builds the same minimal package used for releases from the committed HEAD (or a Git ref such as v0.3.1) and writes the .plasmoid plus its SHA-256 checksum under dist/. Existing output is preserved unless --force is supplied. The archive contains only metadata.json, contents/ and LICENSE.

⚙️ Behavior notes

Cost refresh

Cost scanning is off by default because large local histories can be resource-intensive. Quota refreshes never start local-history cost scans. When the cost section is enabled, automatic scans are serialized and run at most once per provider per hour. Use Refresh cost history on a Codex or Claude page when you need an immediate scan.

Per-provider data source and CLI environment

Source. Some providers have several CodexBar data sources with different speed and credential needs (for example OpenCode Go: the automatic local-database scan versus the API with OPENCODE_API_KEY). The Providers settings page has a source column per provider (Auto, Web, CLI, OAuth, API) that is passed to the CLI as --source. Auto leaves the decision to the CLI. See the CodexBar CLI documentation for what each provider supports.

Environment. Plasma does not pass your interactive shell environment to widgets. Set CLI environment file in the General settings to a file with KEY=VALUE lines (for example ~/.config/codexbar/widget.env, chmod 600; quote values that contain spaces, the file is read like a shell EnvironmentFile). The widget exports those variables only into the codexbar process it starts, so API keys never have to be stored in Plasma's applet configuration. A missing file is ignored. Anything CodexBar itself can read from ~/.config/codexbar/config.json works there as well.

Optional Claude multi-account adapter

Enable Show all accounts from a schema-v1 adapter and set the adapter executable path. Compatible adapters must implement only these CodexBar operations:

--list --json
--switch-to <positive-slot> --json

The widget validates schema version 1 and retains only account slot, optional alias/organizationName/email display identity, active state, the optional disabled rotation flag, usage status, the 5-hour/7-day usage windows, optional model-scoped weekly windows, and optional pay-as-you-go spend (used/limit/pct/currency), which only the adapter can report per account. When present, identity is displayed as alias, then organizationName, then email. The optional isOrganization boolean (set from whether the account has an organization, without exposing its uuid) only adds a Personal/Organization tag when organizationName is empty, so an org account with an unresolved name is still told apart from a personal one.

Each account row may optionally report usageFetchedAt (ISO 8601 timestamp) or usageAgeSeconds (non-negative seconds); when present, the card timestamp and staleness reflect measurement time rather than poll time, so cached usage is shown as stale instead of fresh. When a live fetch fails, a row may instead carry lastGoodUsage with lastGoodFetchedAt/lastGoodAgeSeconds; those windows go through the same strict projection, are timestamped from the last-good measurement, and are labelled last known instead of being shown as current. The widget does not read credentials or profile IDs.

Weekly windows (sevenDay and model-scoped entries) may additively report the adapter's own pace verdict as expectedPct/aheadOfPace; when present it is preferred over the pace line the widget otherwise reconstructs locally. The projectedExhaustionAt/willLastToReset projections are deliberately not read.

Account switches are serialized and only run after an explicit click. The switch action is offered for the ok, api_key, unavailable, token_expired, and foreign_credential statuses (the last two because an explicit switch is what refreshes an expired token or replaces a foreign credential). keychain_unavailable, no_credentials, and relogin_required instead report what has to be fixed outside the widget. A disabled slot is only held out of the adapter's automatic rotation and stays a valid explicit target, so the card labels it Not in rotation without withdrawing the switch action. Any warnings the switch result carries are shown afterwards, including on a successful switch.

Examples:

• Install claude-swap and leave the path empty to use cswap from PATH.
• For another compatible adapter, set its absolute path or a path beginning with ~/.

The CodexBar CLI remains required: normal Claude usage continues to power the panel icon, overview, cost, provider status, and fallback card.

Not ported (macOS-only upstream features)

Menu bar animations (blink/wiggle), WidgetKit widgets, notifications, cost-history and detail-section charts, and the "Add Account" flow. Logins are handled by the provider CLIs themselves.

🙏 Credits & license

MIT, see LICENSE. This is an independent community port; all credit for the concept, the design and the CLI goes to Peter Steinberger's CodexBar. The provider icon SVGs are taken from the upstream repository (MIT). Upstream also ships a standalone Linux desktop app if you prefer a tray application over a Plasma widget.