see your ai usage from the terminal and desktop tray
native • private • open source • 69 providers
codexbar linux shows how much ai usage you have left. it can live in your kde plasma tray, waybar tray, or another linux desktop tray. it also has a terminal app, simple commands, json output, history, alerts, cost reports, and a local dashboard api.
codexbar linux is a native linux fork of steipete/codexbar, which defines the upstream provider behavior this port follows.
- one small native linux app
- kde plasma and status notifier tray support
- waybar support through its normal tray module
- terminal ui with keyboard controls
- text and json commands for scripts
- usage history, alerts, hooks, costs, and sessions
- multiple accounts with separate data
- bounded network requests and private config files
- 69 native providers with no compatibility subprocess
- x86_64 and aarch64 release support
release pages provide a debian package, rpm, appimage, generic archive, and deterministic source archive for the
published version. verify the adjacent .sha256 file before installation.
install a downloaded debian package:
sudo apt install ./codexbar-linux_VERSION-1_ARCH.debinstall a downloaded rpm:
sudo dnf install ./codexbar-linux-VERSION-1.DISTRO.ARCH.rpmrun an appimage without installing system files:
chmod +x codexbar-linux-VERSION-ARCH.AppImage
./codexbar-linux-VERSION-ARCH.AppImagethe appimage does not configure desktop autostart. configure your desktop to run the stable appimage path if you want the status item at login.
install from the aur on arch linux or manjaro:
yay -S codexbar-linuxsudo apt update
sudo apt install build-essential meson ninja-build pkg-config libglib2.0-dev libcurl4-openssl-dev libjson-c-dev libsqlite3-dev libncurses-devsudo dnf install gcc meson ninja-build pkgconf-pkg-config glib2-devel libcurl-devel json-c-devel sqlite-devel ncurses-develsudo pacman -S --needed base-devel meson ninja pkgconf glib2 curl json-c sqlite ncursessudo zypper install gcc meson ninja pkg-config glib2-devel libcurl-devel libjson-c-devel sqlite3-devel ncurses-develgit clone https://github.com/WhiteHades/CodexBar-linux.git
cd CodexBar-linux
make check
sudo make installthe app is now installed as codexbar-linux. it starts in your desktop tray on your next login.
run it now without logging out:
codexbar-linux status-itemthe generic ready-made archive remains available for systems without one of the package formats above.
codexbar linux uses the standard linux status notifier protocol. this is the same tray system used by many chat, sync, and media apps.
the standard plasma system tray finds codexbar automatically. install the app, then log out and back in. you can also run codexbar-linux status-item to show it now.
if it is hidden, open the plasma system tray settings and set codexbar to show when relevant or always show.
if your waybar already has a tray module, codexbar appears automatically.
if it does not, add tray to modules-right in your waybar config and add this section:
"tray": {
"icon-size": 18,
"spacing": 8
}reload waybar after the change.
codexbar works with panels that support status notifier items. ubuntu usually includes this support. on gnome, install or enable the appindicator extension if your tray is not visible.
codexbar never rewrites your panel layout. it joins the tray that your desktop already owns.
see every provider:
codexbar-linux config providersenable a provider:
codexbar-linux config enable --provider openrouteradd an api key without placing it in shell history:
printf '%s\n' "$OPENROUTER_API_KEY" | codexbar-linux config set-api-key --provider openrouter --stdinibm bob accepts the same private config flow, or its standard environment variable:
export BOBSHELL_API_KEY="your-api-key"
codexbar-linux config enable --provider ibmbobnotion ai uses a manual token_v2 session cookie. add an enabled notion entry to the private config file with
"cookieSource":"manual" and "cookieHeader":"token_v2=..."; a browser Cookie header or full Copy as cURL
capture also works. add
"workspaceID":"..." only to select a specific workspace. notion does not use automatic browser import or an
environment variable on linux.
check your setup:
codexbar-linux config validate
codexbar-linux diagnose --provider openrouter --format jsonthe config file lives at ${XDG_CONFIG_HOME:-~/.config}/codexbar/config.json and uses private file permissions.
read the full configuration guide for accounts, sources, themes, and environment options.
open the terminal app:
codexbar-linux tuishow usage:
codexbar-linux usage --provider codex
codexbar-linux usage --provider all --format json --prettyuse the other tools:
codexbar-linux cards --provider all --brief
codexbar-linux cost --provider both --format json
codexbar-linux history --provider codex --format json
codexbar-linux sessions --json
codexbar-linux guard --provider codex --window weekly --min-remaining 20
codexbar-linux waybarrun codexbar-linux --help to see every command.
codexbar linux includes 69 native providers. this includes codex, claude, copilot, cursor, fireworks, gemini, ibm bob, notion ai, openrouter, deepseek, deepgram, groq, kimi, kilo, z.ai, vertex ai, bedrock, xai, and many more.
read the complete provider list.
your provider data stays separated by provider and account. config writes are atomic and private. network responses have size limits. redirects and custom endpoints are checked. secrets are redacted from diagnostics.
read the security guide for the full threat model.
if the tray icon does not appear:
- run
codexbar-linux status-itemin a terminal - check that your panel has a system tray or tray module
- check whether your desktop has hidden the
codexbaritem - run
codexbar-linux diagnose --provider all --format json
if a provider does not work, run codexbar-linux config validate first. do not post api keys, cookies, or account tokens in an issue.
make build
make test
make check
make sanitize
make release
make package
make package-source
make package-deb
make package-rpm
make package-appimage
make check-packagingread the development guide, packaging guide, and release guide.
mit. see license.