claudometer 1.2.0

Live Claude usage limits (session & weekly) on your taskbar / menu bar — so you never hit a limit by surprise.

Claudometer

Your Claude usage limits, always visible — right on your taskbar.
A tiny desktop widget that shows your live session & weekly usage, so you never hit a limit by surprise.

Unofficial — not affiliated with, or endorsed by, Anthropic. Details ↓

---

Why

Claude's Pro / Max / Team plans enforce a rolling 5‑hour session limit and weekly limits. Use Claude Code heavily and it's easy to burn through them mid‑task — then get rate‑limited at the worst moment. Checking today means opening the /usage panel and remembering to look.

Claudometer keeps that number on‑screen all the time, as clean floating text that sits on your taskbar by default — sampling its color so it blends right in:

🖱️ Put it anywhere

The strip is a free‑floating, always‑on‑top widget — not locked to the taskbar. Drag it to a screen edge, over a window, or onto a second monitor, and it remembers the spot.

Wherever it lands, it stays readable: it picks the light or dark palette by contrast against what's behind it, then lifts each label the rest of the way to the WCAG AA ratio if that isn't enough — on a saturated wallpaper the theme greys alone measure about 1.2:1. Severity colours never change hue, because red, amber and green are the message: the numbers only go lighter or darker, and the dots keep their colour outright. The background is never touched: blending into the taskbar is the point. (On macOS the native menu‑bar item is the default; the same floating widget is available with app.py bar — see Platform support.)

• Session 61% — your current 5‑hour window, with a live countdown to reset.
• Weekly 18% — your 7‑day, all‑models usage.
• A color dot (🟢 <50% · 🟡 50–80% · 🔴 >80%) that flips to a clear "limit reached" when you're maxed out, plus a graceful offline state:

Click it for the full breakdown — per‑meter reset times, per‑model usage, light/dark:

What you get

• 🎯 Pace yourself — spot a limit before you hit it.
• ⚡ Zero context‑switch — the number's already there; no panel to open.
• 🔒 Zero setup — reuses your existing Claude login. Nothing to configure.
• 🪶 Featherweight — ~0.03% CPU idle, ~50 MB RAM. You won't notice it.
• 🔔 Alerts — optional desktop toast when you cross 80% / 90%.
• 🟢 Live sessions — a coloured dot per running claude session, right on the taskbar: which is working, which finished, and which is blocked waiting on you. One click — or a global shortcut — lands you in that terminal.
• ⏭️ Resume — one click picks up interrupted work when your limit resets (auto‑resume optional).
• 🖥️ Out of the way — auto‑hides over fullscreen movies/games (or set it to always show).
• ⚙️ Tunable — a built‑in settings panel (no file editing) for theme, meters, alerts, accent, cost view, and more.

---

More screenshots

Windows — the strip on the taskbar with the details popover open:

macOS — native menu‑bar item with a dropdown breakdown:

Threshold alerts — a desktop toast the moment you cross a limit you set:

Live sessions — every running claude session, blocked ones first:

Estimated cost (opt‑in) — today's tokens + a rough dollar figure in the popover (a local estimate, not a bill):

Always‑visible mode — keep it readable even over a fullscreen movie or game:

---

Every state, in pictures

The shots above are the app at its best. These are the app at every setting — each state it can be in, including the quiet ones you only meet once: nothing running, more sessions than fit, the screen it can't read, the session that ended while you were reading it.

Every image here is a real render from the app's own code, built through the same formatters the widget uses. None of it is mocked, so a state that stops working stops generating. Rebuild them with py assets/make_gallery.py (the Tk windows come from capture_answer.py and capture_settings.py, which need a display).

The strip

Each meter combination, each severity, the live‑session dot row filling up and overflowing, and the states where there's nothing to report at all.

…on whatever it's sitting on

The strip samples the colour behind it and paints itself in that, so it can end up on anything. It picks the palette by contrast, then lifts each label to the WCAG AA ratio — on a saturated wallpaper the theme greys alone measure about 1.2:1, which isn't dim, it's absent.

Severity colours are handled separately, because red, amber and green are the message. Recolouring them the way labels are recoloured turns all three into the same near-black on a grey taskbar, which destroys the meaning to fix the legibility. So the numbers move along lightness only — a deeper amber is still obviously amber — and the dots, too small to darken without becoming three identical blobs, keep their colour and gain an edge in that same colour when they'd otherwise disappear.

The details popover

A session row

Each row carries what the session is doing and how long it's been doing it; a blocked one also carries why.

Alerts

The tray icon (Windows)

The number itself is the icon. A blocked session outranks the usage figure — usage is something to pace against, a blocked session is something to go and do — so the disc turns red and counts them instead.

Answering a session (Windows)

---

Install

Requires a Claude Pro / Max / Team subscription, signed into Claude Code at least once (that's where the login lives).

Easiest — one command, any OS:

pipx install claudometer      # no pipx?  →  python -m pip install --user pipx
claudometer

Update later with pipx upgrade claudometer.

Windows:

scoop install https://raw.githubusercontent.com/ali-dev178/claudometer/main/packaging/scoop/claudometer.json

…or download the installer (ClaudometerSetup.exe, offers "start on sign‑in") or the portable Claudometer.exe from Releases.

macOS:

brew install --cask ali-dev178/claudometer/claudometer

…or download Claudometer.dmg from Releases and drag it to Applications.

From source (Python 3.9+):

git clone https://github.com/ali-dev178/claudometer.git && cd claudometer
pip install -r requirements.txt
pythonw.exe app.py bar    # Windows (no console)   ·   python3 app.py   # macOS

Unsigned downloads: on first launch, Windows ("More info → Run anyway") or macOS (right‑click → Open) may ask you to confirm. Installing via pipx / scoop / brew skips that.

Windows 11 tip: new taskbar items can get tucked away — drag Claudometer where you want it; it remembers the spot.

---

Resume when your limit resets

Hit the session limit mid‑task and everything stalls? Claudometer watches your usage recover and helps you pick right back up.

• Tier 1 — notify + one click (default, safe). On reset, a notification appears; click Resume to open a terminal in the interrupted session's folder running claude --resume — you stay in control.
• Tier 2 — auto‑resume (opt‑in, off by default). After a "resuming in 20s — click to cancel" window, it resumes unattended so work continues while you're away.

⚠️ Tier 2 runs Claude Code with nobody watching. It's off unless you set resume_auto = true, and it's guard‑railed: a turn cap plus the safer acceptEdits mode by default (full --dangerously-skip-permissions only if you also opt in). Enable it only for work you trust to run on its own.

---

Live Claude sessions

Running Claude in three terminals and losing track of which one is waiting on you? Claudometer lists every live claude session and what it's actually doing.

Dot	State	Meaning
🔴	needs you	blocked on a permission prompt or a question — with the reason
🟡	working	the model is generating, or a tool is running
🟠	running a command	a shell command specifically
🟢	done	it replied; waiting for your next prompt

Blocked sessions sort to the top and each row shows how long it's held that state.

You don't have to open anything. The strip carries one coloured dot per session — Live ● ● ● — so a glance tells you how many are running and what each is doing. The moment one needs you, the leading dot turns red and stays red until it's dealt with, and the strip pulses once to catch your eye.

• Alerts — a toast when a session needs you, finishes, or stays blocked too long. A "needs you" toast has no timeout: it waits until you click it or the session unblocks. Several at once collapse into one summary rather than burying each other.
• Answer from the toast. When the prompt is short enough to decide from — "run the test suite?" — its choices appear on the toast itself, so a yes costs one click and opens nothing. Longer menus deliberately don't: three words on a card isn't enough to choose between six options, and that's exactly what the window is for.
• Click the toast to answer the session that raised it, without leaving what you're doing.
• A global shortcut (Ctrl+Alt+J by default) goes to whichever session is waiting, from any application.
• Click a row to answer a blocked session, or to bring any other session's terminal forward. Right‑click for open project folder, open transcript, copy session ID / path, and Reply and go.
• Recently finished sessions and a today‑by‑project usage split (with show_cost) live in the tray / menu‑bar menus. In the tray, the icon itself turns red with a count while sessions are blocked.

Answer it from here (Windows)

Clicking a blocked session opens it in a small window showing the question it is actually asking and its choices as buttons. Pick one and it goes straight to that session — with the mouse, or by pressing its number. The global shortcut opens the window and 1–9 answers it, so a blocked session can be dealt with without touching the mouse at all. (Digits go into the message box instead once you click into it, since at that point you're writing rather than choosing.)

The question comes off the session's own screen, because that is the only place it exists — Claude Code's transcript records a tool call after it has been answered, so while a session is waiting the transcript doesn't know what it asked.

The window stays open once you answer. Choosing "chat about this" starts a conversation, not an ending, so it shows what the session says back and keeps taking messages — you only go to the terminal if you want to. What it says is shown as prose rather than as a copy of the terminal: output is wrapped to the terminal's width and studded with glyphs, and the sentence is the part that matters.

It handles the rest of what a session can do to you: it says when one is working (anything you send is queued, exactly as typing into the terminal would be), when a menu moved under your pointer (that choice is refused rather than sent to a question you never read), and when the session has ended (the last thing it said stays up; nothing more can be sent).

It closes itself. The window opened because something needed answering; once nothing does — the session has replied, or ended — it counts down and goes, telling you before it does. Typing, clicking or sending resets that, and a half-written message keeps it up indefinitely, so it can't take anything from you. A session that is still asking, or still working, is never retired. Esc closes it now.

Why this is safe. Input is delivered to the session's process, not to a window — several sessions routinely share one terminal and nothing in the process tree tells their tabs apart, so anything window-based would be a coin flip. Every send re-checks the session is still live first, since a process id gets reused. Windows only: this uses AttachConsole, and neither macOS nor a modern Linux has an equivalent — there, clicking a blocked session takes you to its terminal instead. Turn it off with sessions_answer = false.

It reads ~/.claude/sessions locally — the same registry Claude Code maintains — about once a second. Nothing is sent anywhere.

Instant alerts via hooks (optional — it edits Claude Code's settings)

By default sessions update within about a second, which needs no setup at all. Turning on Instant alerts additionally registers four hooks (Notification, Stop, SessionStart, SessionEnd) in ~/.claude/settings.json so changes land the moment they happen — and carry the real prompt text a session is blocked on, instead of a generic category.

Because that's another app's config file, it's handled carefully: you see the exact JSON and confirm before anything is written, the original is backed up, your other settings and anyone else's hooks are preserved, and switching it off removes exactly those entries. Pre/PostToolUse are deliberately not registered — they fire constantly and each one costs a process spawn inside your session.

The hook runs a small relay copied to ~/.claudometer, not from the app folder, so updating or uninstalling Claudometer can't leave Claude Code invoking a path that no longer exists. If Claudometer stops running entirely, the relay notices after a week and removes the hooks, the queue and itself — so an uninstall tidies up even if you forget to switch it off first.

---

Configure

In‑app (recommended): click ⚙ Settings in the popover (or right‑click the strip → Settings…). Adjust theme, meters, accent, poll interval, alerts, cost view, fullscreen behavior, and resume — changes apply instantly and save to ~/.claudometer.toml for you.

Or edit the file by hand — copy claudometer.example.toml to ~/.claudometer.toml:

poll = 90                        # seconds between polls (60–300)
theme = "auto"                   # auto | light | dark
metrics = ["session", "weekly"]  # which meters on the strip
hide_on_fullscreen = true        # false = stay visible, even over fullscreen apps
alerts = true                    # desktop toast on threshold crossings
alert_thresholds = [80, 90]
show_cost = false                # estimated token/$ line in the popover
# accent = "#d97757"             # override the accent color

resume_notify = true             # one-click resume when the session limit resets
resume_auto = false              # Tier 2: unattended auto-resume (opt-in, risky)
resume_prompt = "Continue where you left off."
resume_max_turns = 30            # Tier 2: cap agentic turns
# resume_skip_permissions = false  # Tier 2: --dangerously-skip-permissions (else acceptEdits)

sessions = true                  # show live Claude Code sessions
sessions_on_strip = true         # "Live N" count on the taskbar strip
sessions_max_rows = 6            # rows before the rest collapse to "+N more" (1-12)
sessions_alerts = true           # toast on session changes
sessions_alert_on = ["waiting", "idle", "stuck"]   # + "gone"
sessions_stuck_minutes = 10      # nudge if still blocked after this (0 = never)
sessions_quiet_foreground = true # stay quiet for the terminal you're using
sessions_hooks = false           # instant alerts (edits ~/.claude/settings.json; asks first)
sessions_hotkey = "ctrl+alt+j"   # global shortcut to the waiting session ("" = off)

Optional environment overrides:

Env var	Purpose
CLAUDOMETER_CONFIG	Path to the config file (default ~/.claudometer.toml).
CLAUDE_CONFIG_DIR	Where to read Claude credentials (default ~/.claude).
CLAUDE_WIDGET_POLL	Poll interval in seconds (60–300), for the tray/menu‑bar.
CLAUDE_WIDGET_FAKE	Testing: "95,40,0" = session,weekly,scoped % (skips the network). Try $env:CLAUDE_WIDGET_FAKE="95,40,0"; py app.py bar to preview the red state.

On macOS / Linux the default menu‑bar / tray shows live usage; the full feature set (alerts, cost, resume, themes, settings panel) runs in the floating widget — app.py bar (see Platform support).

Run modes: app.py bar (Windows taskbar strip — default & recommended) · app.py tray (tray icon) · app.py both · app.py (auto per platform). Strip: left‑click = popover · drag = move it anywhere on screen (remembered) · right‑click = menu.

▶ Try a demo

Want to see every feature without waiting to hit a real limit? Click Settings → ▶ Try a demo (or right‑click the strip → Try a demo, or run app.py demo). Your widget switches in place (one window, not a second) into a ~50‑second offline tour covering every state — all clearly badged DEMO:

• the color dot cycling green → amber → red
• session and weekly threshold alerts (80% / 90%)
• the limit‑reached and rate‑limited states
• resume‑on‑reset — both Tier 1 (notify + one click) and Tier 2 (auto‑resume countdown)
• the estimated cost line (click the strip to see it) and the graceful offline state
• live sessions end to end — the dot row filling up and overflowing, a session blocking (red dot, red strip dot, a pulse and a toast that waits for you), it being answered, two finishing at once as one summary, and one ending
• answering a blocked session in place — the real window opens on the tour's blocked session, showing its question and choices as buttons. It reads a canned screen and sends nothing: the tour's process ids are invented, and one could belong to something real

Pick ◼ Exit demo to snap back to your real usage. No network, no credentials, nothing real touched.

Start on login: flip the Start on login toggle — in Settings → Display on the Windows/floating widget, or Settings → Start at login in the macOS menu bar. It wires up the native per‑user autostart for you (Windows Run key · macOS LaunchAgent · Linux XDG autostart) and reproduces however you launched the widget, so there's nothing to hand‑edit. To do it manually instead:

Manual auto-start (advanced)

Windows: add a shortcut to pythonw.exe "…\app.py" bar in shell:startup. macOS: add the standalone Claudometer.app to System Settings → Login Items, or use a LaunchAgent for a source install —

~/Library/LaunchAgents/com.claudometer.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.claudometer</string>
  <key>ProgramArguments</key>
  <array><string>/usr/bin/python3</string><string>/absolute/path/to/claudometer/app.py</string></array>
  <key>RunAtLoad</key><true/>
</dict></plist>

Then: launchctl load ~/Library/LaunchAgents/com.claudometer.plist

---

How it works

Claudometer reads the OAuth token Claude Code already stores locally (~/.claude/.credentials.json, or the macOS Keychain) and polls Anthropic's server‑reported usage endpoint — the same source the /usage panel uses:

GET https://api.anthropic.com/api/oauth/usage

So it shows true plan % from Anthropic's backend — not a local token‑cost guess (unlike tools that tally *.jsonl transcripts). Tokens refresh automatically when they expire.

• Privacy — your token is read locally; the only network call is the authenticated request to api.anthropic.com. No third‑party servers, no telemetry, no analytics.
• Footprint — ~0.03% CPU idle, ~50 MB RAM. The strip only redraws when a value changes; the popover only while it's open.

---

Troubleshooting

It shows offline right after I start it, then starts working once I open Claude Code in a terminal. Expected. Claudometer has no login of its own — it reads the OAuth token Claude Code stores in ~/.claude/.credentials.json on every poll. If that token has expired and Claudometer can't refresh it at that moment (or the first poll hits a brief network blip at login), it degrades to a graceful offline state instead of nagging you to re‑login. Opening Claude Code refreshes the token and rewrites the credentials file, so Claudometer's next poll picks up the fresh token and stats appear. It also self‑heals on its own — it proactively refreshes a soon‑to‑expire token — so you don't strictly need to open a terminal.

How soon do stats appear? Within one poll interval — up to ~90s by default (CLAUDE_WIDGET_POLL, clamped 60–300s) — once a usable token is on disk and the account has active limit windows. A grey - (no data) means the token is fine but there's no usage to show yet; that's different from offline.

It says offline and never recovers. Confirm Claude Code itself works (claude in a terminal), check your internet connection, and make sure ~/.claude/.credentials.json exists (or CLAUDE_CONFIG_DIR points at the right folder). If Claude Code has fully logged out, re‑login there and Claudometer will follow.

---

Platform support

Platform	UI	Status
Windows 10/11	Taskbar strip + click‑to‑open popover — full feature set	✅ Full
macOS	Menu‑bar item (default) or the full floating widget via app.py bar	✅ Full
Linux	Tray icon (default) or the floating widget via app.py bar	🧪 Experimental

The floating widget is one cross‑platform codebase — the same strip, drag, popover, alerts, resume, settings panel, cost and demo run on every OS. On macOS the default is the native menu bar; python3 app.py bar gives you the full floating widget.

Roadmap

Shipped: desktop alerts · config file + in‑app settings panel · estimated‑cost view · standalone binaries + release CI · pipx / Scoop / Homebrew installs · cross‑platform floating widget (macOS/Linux) · one‑click Check for Updates · Start on login toggle · live Claude session monitor (statuses, alerts, click‑to‑focus, per‑project usage).

Next: usage sparkline over the session · per‑model cost breakdown · published winget listing.

Ideas and PRs welcome — open an issue.

Contributing

pip install -r requirements.txt && py app.py bar   # run it
pip install -r requirements-dev.txt && pytest        # run the tests (also in CI)

usage_core.py = data/auth (no UI deps) · render.py = all the Pillow drawing · settings.py / cost.py / resume.py = config, cost estimation, session‑resume · the platform adapters (widget_bar.py, menubar_mac.py, tray_windows.py) are thin. The tests/ suite (~385 checks on the core logic) runs on every push via CI; regenerate the README images with py assets/make_assets.py (stills), py assets/capture_settings.py (the Settings window) and py assets/make_hero_gif.py (the animated hero).

⚠️ Disclaimer

Claudometer is an independent, unofficial tool — not affiliated with, authorized, or endorsed by Anthropic. It relies on an undocumented usage endpoint that may change or break at any time, and reads your local Claude Code credentials on your own machine. Use at your own risk and in accordance with Anthropic's Terms of Service. "Claude" is a trademark of Anthropic, PBC.

License

MIT © 2026 Muhammad Ali