Jatify Claude Usage Tracker All Jatify projects

Claude Usage Tracker

Your Claude Code plan limits in the KDE panel — pace forecasts, activity, and live sessions at a glance.

See your Claude Code plan limits on the Linux desktop: how much of the 5-hour, weekly and per-model weekly (Fable) limits you’ve used, when each one resets, and whether you’re on pace to run out before it does. It shows only the limits your plan has: verified Ultra accounts have no 5-hour limit, so they see weekly and Fable instead. If you also use Codex or Antigravity, their limits appear alongside.

The three panel styles, Numbers, Meters and Ring, each showing 5-hour 38%, weekly 61% and 3 working sessions; below, Numbers with Codex and Antigravity switched on too

Plan tab: 5-hour, weekly and Fable limits with pace markers and forecasts, a chart of the current 5-hour window, and a verdict Activity tab: tokens for today, 7 and 30 days, a 12-week activity grid, and models and projects ranked by tokens Sessions tab: running Claude Code sessions grouped into working and waiting for you Other tools tab: Codex 5-hour and weekly limits, and Antigravity quotas per model

Screenshots use demo data.

Unofficial. This project is not affiliated with or endorsed by Anthropic. It reads an undocumented endpoint (/api/oauth/usage) that Claude Code itself uses, which may change or disappear without notice.

It ships two independent front-ends over the same data:

What it isPick it if
Plasma applet (plasmoid/)Native KDE Plasma 6 panel widget with a full popupYou use KDE Plasma 6
Tray widget (usage_tray.py)PySide6 system-tray icon and a small always-on-top overlayYou use any other desktop with a system tray

Features

Colours follow the pace verdict, not the raw percentage: blue when you’re under pace, amber when you’re close, red when you’re on track to hit the limit before it resets. All three, and the orange accent, can be changed in the applet’s settings.

In the panel, your plan’s first two limits in one of three styles: Numbers (5h 38 wk 61, or wk 24 fable 3 on Ultra), Meters (two small bars with an even-pace tick) or Ring (two rings, square enough for a vertical panel). Settings → Panel has a switch per tool: Claude (on by default), Codex (cx 5h 0 wk 16) and Antigravity (ag 87, its most-used model), so the panel shows any mix. The widget dims when it’s showing a cached reading, and a pulsing count appears while Claude Code sessions are working.

In the applet’s popup:

  • Plan: every limit on your plan, each bar with an even-pace tick and a faded forecast of where you’ll be at reset, then a chart of the current window for any of them with a plain verdict (“At this pace you’ll use about 63% by the reset”).
  • Activity, read from Claude Code’s local logs on this computer: tokens for today, 7 and 30 days, a 12-week activity grid, and models and projects ranked by tokens for today, 7 days, 30 days or all time.
  • Sessions: every running Claude Code session, working ones first, and what each is doing right now (Editing routes.ts, Running: <command>, Thinking, Waiting for you).
  • Other tools: plan limits of other AI coding tools on this computer. Codex: its 5-hour and weekly limits, read from Codex’s own session logs (as fresh as your last Codex turn). Antigravity: each model’s quota and reset, read from the running Antigravity app (open it to see them). The tray overlay and tooltip list these too.
  • Desktop notifications when a limit crosses 75%, 90% or 100% (configurable), and when a window you were warned about resets.
  • Plain-language errors: “Login expired: open Claude Code once to refresh it”, “Usage endpoint is rate-limiting: will retry on the next poll”, and so on, with the last good reading still on screen.

The tray widget shows the first limit’s percentage (5-hour, or weekly on Ultra) as its icon, coloured green to red, with every limit and their reset countdowns in the tooltip and the overlay. Left-click toggles the overlay; right-click has Refresh now, Show/hide panel and Quit.

Requirements

  • Linux.
  • Claude Code installed and signed in with a Claude subscription (Pro, Max, Ultra, Team or Enterprise). API-key logins have no plan limits, so there’s nothing to show.
  • Python 3.11 or newer.
  • Applet: KDE Plasma 6. No Python packages beyond the standard library.
  • Tray widget: a desktop with a system tray. PySide6 (Qt 6 for Python) is used from your distribution, or installed automatically.
  • Optional: notify-send (package libnotify) for the applet’s desktop notifications.
  • Optional: Codex CLI signed in with ChatGPT, and/or Antigravity, for the Other tools tab. Gemini CLI isn’t shown: Google ended its personal tier in favour of Antigravity.

Install

git clone https://github.com/imdizmo/claude-usage-tracker.git
cd claude-usage-tracker
./install.sh applet   # KDE Plasma 6: the panel widget
./install.sh tray     # any other desktop: the tray widget

Both install for your user only, with no root needed. Run the same command again to update after pulling new changes.

Applet. Then right-click your panel, choose Add Widgets…, and drag Claude Code Usage onto it.

Tray. It starts at login from then on. To start it right away:

claude-usage-tray &

It uses your distribution’s PySide6 if it’s installed (pacman -S pyside6, apt install python3-pyside6.qtwidgets, dnf install python3-pyside6). Otherwise the installer puts PySide6 in a private environment under ~/.local/share/claude-usage-tracker/ (about 260 MB).

To try the tray without installing anything, run python3 usage_tray.py from the repository.

Configuration

Applet settings live in its own window: the gear icon in the popup, or right-click the applet and choose Settings…. Changes apply immediately.

The settings window: check interval, notification thresholds, panel style, a switch per tool for the panel, session refresh and colours

SettingDefault
Check plan usage every5 minutes3, 5, 10, 15 or 30 minutes. The endpoint rate-limits quickly; below 5 minutes you’ll see more cached readings.
Notify when a limit reaches75%, 90%, 100%Any of 50 / 75 / 90 / 100%.
Notify when a limit resetsonOnly for windows you were warned about.
Panel styleMetersNumbers, Meters or Ring.
Show Claude / Codex / Antigravityon / off / offWhich tools the panel shows. Antigravity shows its most-used model.
Show second limitonIn the panel, for Claude and Codex.
Show working sessionsonThe pulsing count in the panel.
Refresh session status every5 secondsLocal files only, no network.
Coloursorange accent; blue, amber, redAccent, on pace, close, over pace. Click a swatch to pick; Reset to defaults undoes it.

The tray widget has no settings. It checks every 5 minutes and leaves notifications to the applet.

How it works

Plan limits. Every few minutes it calls GET https://api.anthropic.com/api/oauth/usage with the OAuth token Claude Code already stores in ~/.claude/.credentials.json. There’s no API key and nothing to log into: if Claude Code works on this computer, this works.

Rate limiting. That endpoint returns HTTP 429 if it’s polled too often. On any failure (429, offline, expired login) both front-ends show the last good reading, marked as cached, and keep the reset countdowns ticking from the cached reset times. If you run both, the tray reuses a reading the applet made in the last few minutes instead of making a second request.

Claude Code activity. The Claude Code tab reads the session logs in ~/.claude/projects/**/*.jsonl and the session files in ~/.claude/sessions/. The first scan can take a few seconds on a large history. After that, only newly appended lines are read.

Other tools. Codex writes its plan limits into its own session logs (~/.codex/sessions/) with every turn; the Other tools tab shows the newest reading, so it’s as fresh as your last Codex use. Antigravity’s quotas come from the Antigravity app itself while it runs: the same local request its own status bar makes, to its language server on 127.0.0.1. When Antigravity is closed, the tab says so.

Privacy

  • Network: the only request that leaves your computer is the one above, to api.anthropic.com. Antigravity’s quotas are read from the running app over 127.0.0.1. There is no telemetry.

  • Credentials: ~/.claude/.credentials.json is only ever read, never written, copied or logged.

  • Stored locally: in ~/.cache/:

    • claude-usage.json: the last usage reading.
    • claude-usage-state.json: a week of usage readings and which alerts were sent.
    • claude-usage-stats.json: per-day token counts by model and project folder name, plus how far each log file has been read.

    Conversation content is never stored. Delete these files at any time to reset history, alerts and the log scan.

Troubleshooting

You seeWhat to do
Claude Code isn’t signed in on this machineRun claude and log in.
No Claude.ai login in ~/.claude/.credentials.jsonYou’re signed in with an API key, which has no plan limits. Log in with a Claude.ai account instead.
Login expired: open Claude Code once to refresh itStart Claude Code once. The widget re-reads the token on every check and recovers on its own.
Usage endpoint is rate-limitingNothing; it retries on the next check. If it happens often, check less frequently.
Numbers dimmed, “Showing the reading from HH:MM”A cached reading is being shown. The reason is shown next to it.
Tray: No system tray availableYour desktop has no system tray. On GNOME, install the AppIndicator extension.
Tray overlay in the wrong place on WaylandThe tray runs under XWayland (QT_QPA_PLATFORM=xcb) so it can position the overlay. Drag it where you want it.

Uninstall

./install.sh uninstall

This removes the applet, the tray, its launcher and its autostart entry. Your cached readings are kept; delete them with rm -f ~/.cache/claude-usage*.json.

Development

plasmoid/
  metadata.json            applet metadata
  contents/code/fetch.py   all data work: API, cache, alerts, log scan, live sessions, other tools
  contents/config/main.xml settings and their defaults
  contents/ui/             QML: main.qml (panel + popup), PlanPage, ActivityPage,
                           SessionsPage, OthersPage, SettingsWindow, Theme.js (palette),
                           Colours.qml (user colours) and small shared components
usage_tray.py              PySide6 tray front-end; imports fetch.py
install.sh                 install / update / uninstall / test
docs/                      README screenshots

fetch.py is a stand-alone command-line script; the applet runs it and reads its JSON output:

python3 plasmoid/contents/code/fetch.py           # plan usage (also sends alerts)
python3 plasmoid/contents/code/fetch.py --stats   # Claude Code activity from local logs
python3 plasmoid/contents/code/fetch.py --live    # running sessions
python3 plasmoid/contents/code/fetch.py --others  # Codex and Antigravity limits

Tests. The self-tests use only temporary files. They don’t touch your ~/.claude or ~/.cache and make no network requests:

./install.sh test

To try the applet without adding it to your panel, use plasmoidviewer from the plasma-sdk package:

plasmoidviewer -a plasmoid

Issues and pull requests are welcome. Please run ./install.sh test before sending a change.

License

MIT. See LICENSE.