A native panel applet showing Codex and Claude Code subscription usage. Click it for usage bars, reset countdowns, and the time of the last reading. The panel shows only a compact half-circle icon; usage details stay in the menu. Expired snapshots are never assumed to be zero.
Click the icon → Sign in to Codex… or Sign in to Claude Code…. A terminal opens the provider's official browser login. These actions use the same account as your installed CLI, so signing into another account changes that CLI's login too. The applet does not collect passwords or store tokens. After login, press Enter to close the terminal; Codex usage refreshes automatically. For Claude, restart Claude Code and complete a response to populate the applet. Open Claude usage in browser opens the account usage page for an immediate check; your browser may be signed into a different account than the CLI.
Download the latest release — choose ai-usage-applet-1.0.0.zip, extract it, then open a terminal inside the extracted folder. Run the installer below as your normal user (no sudo).
Requires Cinnamon, Python 3, a Codex CLI, and Claude Code 2.1.251+. Sign-in actions require GNOME Terminal or x-terminal-emulator. No pip/npm packages are needed. This applet is for Cinnamon, not MATE or Xfce.
python3 install.pyThen open System Settings → Applets, select AI Usage, and click +. Restart Claude Code and send a message to populate its usage. Existing terminal status-line commands are preserved and still receive their original input. The installer backs up existing Claude settings before editing them. Project-specific Claude statusLine settings can override this user-level bridge.
Right-click the applet → Configure to change the refresh interval (default
120 seconds), Codex executable path, or Claude Code executable path. If Cinnamon's PATH does
not include Codex, enter its absolute path (command -v codex).
Codex uses the official codex app-server account/rateLimits/read method with
your existing CLI login. No prompts or model generations are made. API-key-only
accounts may not return subscription limits. Network failures retain the last
reading, visibly marked stale.
Claude uses the official status-line rate_limits payload. It does not read
credentials or call undocumented OAuth endpoints. Limits are supplied for
supported subscriptions/gateway accounts after an API response. Claude must
be active to refresh its snapshot; usage from other devices is not polled.
Snapshots older than 15 minutes are marked stale. Multiple sessions use the
most recently received snapshot. Switching accounts requires a new reading.
Only normalized percentages, reset timestamps, and update timestamps are saved
under ${XDG_CACHE_HOME:-~/.cache}/ai-usage-applet/, with private file permissions.
Conversation text, tokens, credentials and full status-line payloads are not saved.
python3 ai-usage@local/usage.py
python3 -m unittest discover -s tests -vIf Claude has no data, check its version and subscription, restart the CLI,
and complete a response. If Codex is unavailable, run codex login and check
your network and executable setting. Cinnamon applet errors appear in Looking
Glass (Alt+F2, lg). A desktop logout/login can refresh Cinnamon's applet list.
Remove AI Usage from the panel first. In Claude's settings.json, restore just
statusLine from the installation backup (or remove that property if it did
not exist previously). The original value is also stored in
~/.local/share/cinnamon/applets/ai-usage@local/previous-statusline.json.
Then delete the installed applet directory and the usage cache. Do not restore
an entire old settings file if you have made other settings changes since.
python3 -m unittest discover -s tests -v
node --check ai-usage@local/applet.js
python3 build.pyThe build writes a source ZIP and SHA-256 checksum into dist/. The package
contains only explicitly listed project files. Automated checks cover usage
parsing, the Codex protocol, login command handling, and installation behavior.
Cinnamon UI loading was verified on the developer's desktop; other versions
may need compatibility fixes.
Report bugs through GitHub Issues. Include your Mint/Cinnamon and CLI versions, without credentials or private conversation logs. Contributions are welcome.
MIT. Independent community project; not affiliated with Linux Mint, OpenAI, or Anthropic. Provider names identify the supported services.