Claude Code plans have two limits: one for each 5-hour window and one for the week. Claude Usage Tracker puts both in the KDE panel, with when each one resets and whether I’m on pace to run out before it does. This note is how it works.
Two front ends, one script
There are two ways to run it: a native Plasma 6 applet written in QML, and a tray icon written with PySide6 for other
desktops. Both read their numbers from the same small Python script, fetch.py, which uses only Python’s standard
library. The applet runs the script and reads the JSON it prints, and the tray icon imports it directly.
The tray icon has one quirk. On Wayland an app can’t choose where its own window appears, so the tray version runs through XWayland, where it can place its popup next to the icon.
Where the numbers come from
Claude Code already knows your usage. It’s signed in with an OAuth token that it keeps in ~/.claude/.credentials.json,
and with it Anthropic will report your current usage. The tracker reads that token and asks Anthropic’s usage
endpoint with it. The file is
only read: never written, copied or logged.
The Activity tab doesn’t need the network at all. Claude Code writes a log for each session under ~/.claude, and
the tracker adds up the input, cache and output tokens in them for today, the last 7 days and the last 30. The
Sessions tab reads which Claude Code sessions are running, and checks each process really still exists, because
Linux reuses process IDs.
The pace forecast
The forecast is deliberately simple. If 30% of the window has passed and you’ve used 24% of your limit, at the same rate you’d finish the window at 80%:
forecast = used ÷ share of the window elapsed
It stays quiet until 5% of the window has passed, because a single busy session early on would otherwise forecast something absurd. The code says this out loud in a comment: bursty sessions overshoot early. The verdict under each limit follows from the forecast. Over 100% is Over pace, 80% or more is Close to pace, and anything below is Under pace.
What went wrong along the way
A rate limit. The first version asked for your usage every 60 seconds and soon got 429 Too Many Requests. Now it
asks every 5 minutes. When a request fails it keeps the last good reading, marks it as stale, and keeps counting down to
the resets from the times it already knows. Running both front ends at once doesn’t double the requests: the tray reuses
any reading younger than 270 seconds.
Gigabytes of logs. Claude Code’s session logs grow fast. Reading them all on every refresh would be slow, so the tracker remembers how far it got in each file and only reads what’s new. Lines that can’t contain usage are skipped before they’re parsed.
Counting things twice. One reply from Claude can be written to the log several times, once per part of the message, so a naive sum overcounts. The tracker counts each message once, by its ID. It also skips placeholder entries that aren’t real model calls, and leaves a half-written last line for the next scan.
Tiny differences. The reset time changes by microseconds between requests, which made the tracker think the window had moved. It now compares reset times to the minute. It also writes its cache files atomically, writing a temporary file and then renaming it, so the applet never reads one half-written.
Privacy
The tracker makes one kind of network request, to api.anthropic.com, the same server Claude Code already talks to.
There’s no telemetry. It keeps three small files in ~/.cache with numbers in them, and never stores what you said to
Claude or what it said back.
Testing
There’s no test framework, which keeps the script free of dependencies. Instead fetch.py --selftest runs 39 checks
on temporary files, with no network. GitHub Actions runs them on Python 3.11 and 3.13 and checks the install script
with shellcheck.
Where it is now
Version 1.0.0 is on GitHub under the MIT licence, with an install script for the applet and the tray icon.