panithannanti/claude-usage-widget

claude-usage-widget is a small desktop widget for Mac computers that shows how much of your Claude Code usage limit you have left. It runs through Übersicht, a free tool that lets people put custom widgets on their Mac desktop, and it displays session, weekly, and per-model usage as progress bars that turn from blue to yellow to red as you get closer to your limit. The widget works by reading the login token that Claude Code already stores on your computer after you sign in, then asking Claude's usage endpoint for your current numbers every ten minutes. Because it uses the same connection method as the built in usage command in Claude Code, it avoids the login wall that would normally block a background script from checking usage on your behalf. It also shows countdown timers for when your session and weekly limits reset, and a badge for which subscription plan you are on. A cartoon capybara mascot bobs on top of the card as a small decorative touch. You can drag the widget anywhere on your screen and it remembers where you left it, choose which monitor it appears on if you have more than one, and collapse it into a small circle showing just your session percentage. There is also a refresh button to pull new numbers immediately and a login button that opens a terminal window if your session has expired. To avoid overloading Claude's servers, the widget caches results for five minutes and automatically pauses requests for fifteen minutes if it gets a rate limit error, showing your last known numbers in the meantime rather than going blank. It also refreshes your login token in the background before it expires, so you should not need to log in again very often. Setup is a Mac only shell script installer that installs Übersicht if needed, copies the widget files into place, and turns the widget on right away. An uninstall script is included to remove everything cleanly. It requires macOS, the Claude Code command line tool already installed and logged in, Übersicht, and Python 3, which comes preinstalled on Mac.