Fork variant (branch
markus-variant): dual-provider version showing Claude and Codex as two concentric panel gauges. Claude usage comes from the CodexBar CLI itself viacodexbar usage --provider claude --source oauth— the explicit OAuth source reads~/.claude/.credentials.jsonand queries Anthropic's usage API directly, so it counts every client (Claude Code, Claude Desktop, editor plugins). The explicit flag is required on Linux: CodexBar's auto pipeline fails there (Web cookies are macOS-only, and the CLI PTY fallback returns only a subscription notice without quota numbers for some accounts).Other changes vs. upstream: provider order Claude-first (the 5-hour window is the critical one), runtime contrast detection (menu background luminance is measured, text renders solid black or white — works on light and dark themes), "Refresh now" keeps the menu open, tooltips include reset times, and expired reset timestamps are shown as such instead of "Resets in 0m".
The text below is the original upstream README.
A Linux Mint Cinnamon panel applet for displaying Codex usage from steipete/CodexBar.
The applet runs the codexbar CLI, reads its JSON output, and shows a compact
panel gauge based on the primary usage window. Clicking the applet opens a small
details popup with session, weekly, extra usage, cost, refresh status, and error
information when available.
The applet is confirmed working with the Codex provider. Support for the other providers exposed by CodexBar is still considered beta, and feedback from testers is welcome. If you try another provider, please report what works, what does not, and include a sanitized sample of the JSON output when possible.
- Linux Mint Cinnamon, or another Cinnamon desktop that supports local applets
- CodexBar installed and working
- A
codexbarexecutable available on your machine
By default, this applet expects CodexBar at:
/opt/apps/codexbar/codexbarYou can change that path in the applet settings after installation.
Before installing the applet, make sure CodexBar can produce JSON:
/opt/apps/codexbar/codexbar usage --format json --provider codexProvider failures are okay as long as CodexBar still emits JSON. The applet is designed to show CodexBar error responses instead of crashing.
Clone this repository:
git clone <repo-url>
cd codexbar-appletCreate Cinnamon's local applets directory if needed:
mkdir -p ~/.local/share/cinnamon/appletsSymlink this checkout into Cinnamon's applet directory:
ln -s "$PWD" ~/.local/share/cinnamon/applets/codexbar@localOpen System Settings -> Applets, find CodexBar, and add it to the panel.
If the applet does not appear, restart Cinnamon:
- Press
Alt+F2 - Type
r - Press Enter
You can also log out and back in.
Pull the latest changes in your checkout:
git pullThen remove and re-add the applet, or restart Cinnamon, so the updated JavaScript and stylesheet are reloaded.
Open the applet's settings from Cinnamon's Applets panel.
Available settings:
- CodexBar command path: path to the
codexbarexecutable - Provider: defaults to
codex - Refresh interval: defaults to 60 seconds
The applet runs a command like:
/opt/apps/codexbar/codexbar usage --format json --provider codexThe panel indicator is a tiny gauge sourced from CodexBar's primary limit data:
primary.usedPercentcontrols the gauge fill- Green means low usage
- Amber means elevated usage
- Red means usage is near 100%
The popup uses CodexBar's primary and secondary limit windows for Session
and Weekly usage, and shows additional supported fields when present.
If the applet shows an error, run the configured command manually:
/opt/apps/codexbar/codexbar usage --format json --provider codex --prettyCommon things to check:
- The CodexBar path in applet settings is correct
- CodexBar is installed from steipete/CodexBar
- CodexBar can access the account/provider you selected
- Cinnamon was restarted after installing or updating the applet
Applet logs can usually be viewed with:
tail -f ~/.xsession-errors