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.

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.

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
  

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.

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.

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.

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.

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.