Claude Usage Widget CLI
An always-on-top widget and a CLI show Claude Code limits for 5 hours and 7 days, token burn and the cost of each turn.
- 85 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The widget holds access to the Claude Code subscription token and calls Anthropic servers with it.
- It reads Claude Code conversation logs with the content of your sessions.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/claude-usage-widgetDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The widget holds access to the Claude Code subscription token and calls Anthropic servers with it.
- It reads Claude Code conversation logs with the content of your sessions.
This is third-party code. Review the repository files before installing.
What it does
Claude Usage Widget is a cross-platform PySide6 (Qt) widget that shows Claude Code limits in real time. A compact always-on-top panel shows session and weekly utilization, reset timers, a tokens-per-minute badge, a subagent counter and a scrolling ticker with the cost of each turn. A click opens a window with forecasts, 5-hour and 7-day sparklines, a 90-day heatmap, a 52-week calendar, cost by model and project and a weekly report written by Claude. There are 11 themes, Bars and Gauge views, fast-burn alerts and an optional second provider, OpenAI Codex. CLI mode (`--json`, `--once`, `--field`, `--export`) suits scripts, and `--statusline` plugs into the Claude Code status line.
Who it is for. Claude Code subscribers who want to see remaining limits and token burn without opening settings.
Good fit when
- The five-hour window is ending and you need to know whether the limit lasts until reset.
- A session suddenly burns tokens and you want to see the spike and get a notification.
- The Claude Code status line is fed usage data through `--statusline`.
- Once a week usage by project and model is exported to CSV or JSON.
Not a fit when
- A subscription token must not go to third-party programs: the widget uses it to request limits.
- An environment without a graphical desktop or Python 3.10: both are required.
- Calls to third-party feeds are forbidden by policy: the news ticker makes them when enabled.
Example request
Install claude-usage-widget, run `claude-usage --detach` and show how long until the weekly limit resets and which project spends the most.Limitations
Python 3.10 or newer and an authenticated Claude Code are required: the widget reads the OAuth token from `CLAUDE_CODE_OAUTH_TOKEN`, then from `~/.claude/.credentials.json`, then from the macOS Keychain, and calls the `/api/oauth/usage` endpoint. Claude Code conversation logs are also read. The optional news ticker contacts Hacker News and is off by default. Once a day the widget checks GitHub releases. Codex data is supported on POSIX only. The project is not affiliated with Anthropic.
How to disable. Quit the widget from the `Quit` menu item and remove the package with `pip uninstall claude-usage-widget`. Remove autostart from desktop settings or the systemd service. Delete the `~/.config/claude-usage/config.json` config by hand.
FAQ
How do I install the widget?
Run `pip install --user --upgrade claude-usage-widget` and start `claude-usage`. A Homebrew formula also exists: `brew install claude-usage-widget`.
Where do the limit figures come from?
From the Claude Code `/api/oauth/usage` endpoint: the same 5-hour and weekly numbers the Claude UI shows.
How do I use it as a CLI?
Run it with `--json`, `--once`, `--field` or `--export csv|json` and add `--days N` for the period. `--statusline` covers the status line.
Can I watch Codex usage too?
Yes, add `"codex"` to `providers` in the config: Codex 5-hour and weekly rows appear. The mode works on Linux and macOS.
Where does the widget go on the network?
To the Claude Code usage endpoint and once a day to GitHub releases. The Hacker News ticker is enabled separately and is off by default.
Discussion
No questions or reviews yet.
Related
CLI toolsA Claude Code plugin: a status line with context, 5-hour and 7-day limits, cost and usage of Codex, Gemini and z.ai
A real-time terminal monitor for Claude Code usage: tokens, messages and cost in the five-hour window, with forecasts and export
A Claude Code status line with 5-hour and weekly limit usage, reset countdowns, model and prompt cache lifetime
A Claude Code status line showing model, effort level, context fill, git branch and the 5-hour and weekly limits.
A limits and token spend monitor for Claude Code, Codex, Antigravity and Grok CLI: macOS menu bar, Windows tray, HTML reports
A Claude Code status line showing 5-hour and 7-day quota use plus the pace: whether what is left lasts until the window resets
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Claude Usage Widget (this card) | no | 85 | |
| ccusage | no | 19,425 | token and cost reports from local logs; the widget shows Claude Code limits in real time and reads the usage endpoint |
| Claude Code Usage Monitor | no | 8,801 | a terminal burn monitor for the five-hour window; the widget adds an on-screen panel, themes and a JSON CLI |
README in short
The README shows panel views, themes, features, requirements, installation through pip and Homebrew, autostart, menus and configuration. A separate section covers the status line cache and the second Codex provider.