claudometer 1.0.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, elegant desktop widget that shows your live session & weekly usage so you never hit a limit by surprise.

Unofficial project — not affiliated with, or endorsed by, Anthropic. See the disclaimer.

---

The problem

Claude's plans (Pro / Max / Team) enforce usage limits — a rolling 5‑hour session limit and weekly limits. If you use Claude heavily (Claude Code, long sessions), it's easy to burn through them without realizing… until you're suddenly rate‑limited in the middle of something important.

Today, checking where you stand means opening the /usage panel or the app and reading it — a context switch you have to remember to do. There's no ambient, at‑a‑glance signal.

The solution

Claudometer keeps your usage on‑screen at all times, as clean floating text on your taskbar:

• Session 61% — how much of your current 5‑hour window is used, with a live countdown to reset (1h 21m left).
• Weekly 18% — your 7‑day all‑models usage.
• A color‑coded status dot (🟢 <50% · 🟡 50–80% · 🔴 >80%) so severity registers in a glance — turning to a clear "limit reached" when you're maxed out, plus a graceful offline state when there's no data:

Click it for a polished breakdown with per‑meter reset times and per‑model (e.g. Fable) usage:

Why you'll want it

• 🎯 Pace yourself — see when you're approaching a limit before you hit it.
• ⚡ Zero context‑switch — the number is 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.
• 🖥️ Stays out of the way — optionally auto‑hides over fullscreen movies, games, and presentations (or set it to always show).
• 🔔 Warns you in time — optional desktop alerts when you cross 80% / 90%.
• ⏭️ Picks up where you left off — when your session limit resets, one click resumes the interrupted work (or auto‑resume, if you opt in).
• 🎨 Looks the part — supersampled rendering, light/dark aware, adapts to your taskbar.
• ⚙️ Yours to tune — a built‑in settings panel (no file editing) for interval, theme, meters, alerts, accent, cost view, fullscreen behavior and resume.

---

Screenshots

Windows — floating strip on the taskbar + click‑to‑open popover with usage meters:

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

Threshold alerts — a desktop toast the moment you cross a limit you set (default 80% and 90%), for both session and weekly:

Estimated cost (opt‑in) — turn on show_cost for a today's‑tokens and rough‑dollar line in the popover (a local estimate from your session logs — not a bill):

Always‑visible mode — set hide_on_fullscreen = false and your stats stay readable even over a fullscreen movie, game, or presentation:

---

Resume when your limit resets

Hit the 5‑hour session limit mid‑task and everything grinds to a halt? Claudometer watches your usage recover, so it can help you pick right back up the moment it does.

• Tier 1 — notify + one click (default, safe). When your session resets, a notification appears; click Resume and it opens a terminal in the interrupted session's folder running claude --resume <id> for you to continue — supervised.
• Tier 2 — auto‑resume (opt‑in, off by default). After a short "resuming in 20s — click to cancel" window, it resumes unattended and headless so work continues while you're away.

⚠️ Tier 2 runs Claude Code with nobody watching. It's gated behind resume_auto = true and ships with guard rails: a turn cap (--max-turns) and the safer acceptEdits permission mode by default (full --dangerously-skip-permissions only if you also set resume_skip_permissions = true). Enable it only for work you trust to run on its own. Output is written to a log in ~/.claude/.

Configure both in the config file.

---

Install

You need a Claude Pro / Max / Team subscription and to have signed into Claude Code at least once (that's where the credentials live).

Heads up: the pipx, scoop, brew, and download methods below light up once the first release is published (a one‑time maintainer step — see packaging/). Until then, install from source — that always works.

Easiest — one command (any OS) 🏆

Installs in an isolated environment and puts claudometer on your PATH:

pipx install claudometer      # don't have pipx?  →  python -m pip install --user pipx
claudometer                   # launch it

Update anytime with pipx upgrade claudometer.

Windows

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

…or grab the installer (ClaudometerSetup.exe, ticks "start on sign‑in" for you) or the portable Claudometer.exe from Releases and double‑click.

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 builds: the downloads aren't code‑signed yet, so on first launch Windows SmartScreen ("More info → Run anyway") or macOS Gatekeeper (right‑click → Open) may ask you to confirm. pipx, scoop and brew avoid this.

First‑run tip (Windows): Windows 11 may tuck new taskbar items away — drag Claudometer where you want it; it remembers the spot.

Usage

Command	What you get
app.py bar	Windows: floating taskbar strip + popover (recommended)
app.py tray	Windows/Linux: notification‑area tray icon
app.py both	Windows: taskbar strip and tray icon
app.py	Default — macOS: menu bar · Windows: taskbar strip · Linux: tray

Interactions (taskbar strip): left‑click = open/close popover · drag = move (remembered) · right‑click = Details / Refresh / Quit.

Auto‑start on login

Windows — press Win+R, run shell:startup, and add a shortcut to:

pythonw.exe "C:\path\to\claudometer\app.py" bar

macOS — add a LaunchAgent at ~/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. (This plist is for the from-source install; if you use the standalone Claudometer.app, just add it to System Settings → General → Login Items instead.)

Configuration

Two ways to set things up — use whichever you prefer:

⚙ In‑app settings panel (recommended)

Click ⚙ Settings in the popover (or right‑click the strip → Settings…). Adjust theme, meters, accent, poll interval, alerts, the cost view, fullscreen behavior and resume — changes apply immediately (no restart) and are written to ~/.claudometer.toml for you, so you never have to touch the file.

macOS: the menu‑bar app is a lighter adapter — its Settings submenu exposes what it actually honors (which meters, poll interval) plus Open config file… for the rest. Alerts, cost, resume, accent and theme currently apply to the Windows strip only (see Platform support).

✎ Or edit the file by hand

Everything works with no config. To customise manually, 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 = keep 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)

Environment overrides:

Env var	Purpose
CLAUDOMETER_CONFIG	Path to the config file (default ~/.claudometer.toml).
CLAUDE_CONFIG_DIR	Where to read Claude credentials/transcripts (default ~/.claude).
CLAUDE_WIDGET_POLL	Poll interval in seconds (60–300). The interval source for the Windows/Linux tray (the macOS menu bar polls at a fixed 90s).
CLAUDE_WIDGET_FAKE	Testing: "95,40,0" = session,weekly,scoped % (skips the network).

Preview the red/alert state with no real load:

$env:CLAUDE_WIDGET_FAKE="95,40,0"; py app.py bar

---

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

The response maps directly onto the UI: the 5‑hour window → Session, the 7‑day all‑models window → Weekly, and any per‑model scoped limits → per‑model rows (e.g. Fable), shown only when your account actually has one. Tokens are refreshed automatically when they expire.

This is true plan % from Anthropic's backend — not a local token‑cost estimate (unlike tools that add up *.jsonl transcript costs).

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.

Behavior notes

• Fullscreen auto‑hide (optional) — by default Claudometer hides itself whenever a fullscreen app is active (movies, games, presentations), using Windows' own SHQueryUserNotificationState plus a foreground‑covers‑the‑screen check, then reappears when you exit. Set hide_on_fullscreen = false to keep it visible even over fullscreen apps. On macOS the menu bar hides in fullscreen natively.
• Performance — ~0.03% of total CPU idle, ~0.2% while you have the popover open, ~50 MB RAM. The strip only re‑renders when a value changes; the popover only while it's open.

Platform support

Platform	UI	Status
Windows 10/11	Taskbar strip + click‑to‑open popover	✅ Full
macOS	Menu‑bar item + dropdown	✅ Menu bar
Linux	Notification‑area tray icon	🧪 Experimental (app.py tray)

Feature scope: the taskbar strip (Windows) has the full feature set — click‑to‑open popover, alerts, estimated cost, resume‑on‑reset, themes, accent, and the config file. The macOS menu bar and Linux tray currently show live usage only. Unifying these is on the roadmap.

Roadmap

Shipped: ✅ desktop alerts · ✅ config file · ✅ estimated cost view · ✅ standalone binaries + release CI.

Next up:

• 📈 A tiny usage sparkline over the session
• 🍎 Unified floating popover on macOS (currently a native menu‑bar item)
• 🧮 Per‑model cost breakdown & weekly totals
• 📥 Published winget / Homebrew listings

Contributions and ideas welcome — open an issue or PR.

Contributing

py -m pip install -r requirements.txt
py app.py bar

usage_core.py holds the data/auth logic (no UI deps), render.py does all the Pillow drawing, settings.py / cost.py / resume.py add config, cost estimation, and session‑resume, and the platform adapters (widget_bar.py, menubar_mac.py, tray_windows.py) are thin. Regenerate the README images with py assets/make_assets.py.

⚠️ Disclaimer

Claudometer is an independent, unofficial tool. It is 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 the 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