From 5e039fa7dc4b7871d58d718b600cd945ca926555 Mon Sep 17 00:00:00 2001 From: Craig Constable Date: Thu, 19 Mar 2026 16:25:22 +1000 Subject: [PATCH] v1.2.3 - Updated README.md --- Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 131 +++++++++++++++++++++++++++++++++++------------------ 3 files changed, 89 insertions(+), 46 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index e5bf07b..51bcf29 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -38,7 +38,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" [[package]] name = "claude-code-usage-monitor" -version = "1.2.2" +version = "1.2.3" dependencies = [ "dirs", "native-tls", diff --git a/Cargo.toml b/Cargo.toml index 0302804..8710ece 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "claude-code-usage-monitor" -version = "1.2.2" +version = "1.2.3" edition = "2021" license = "MIT" description = "Windows taskbar widget for monitoring Claude Code usage and rate limits" diff --git a/README.md b/README.md index 1db478b..f7d84f5 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,116 @@ # Claude Code Usage Monitor -A lightweight Windows taskbar widget that displays your Claude API rate limit usage in real time. +A lightweight Windows taskbar widget for people already using Claude Code. + +It sits in your taskbar and shows how much of your Claude Code usage window you have left, without needing to open the terminal or the Claude site. ![Windows](https://img.shields.io/badge/platform-Windows-blue) -![Rust](https://img.shields.io/badge/language-Rust-orange) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![Screenshot](.github/screenshot.png) -## What it does +## What You Get -Embeds directly into the Windows taskbar and shows two progress bars: +- A **5h** bar for your current 5-hour Claude usage window +- A **7d** bar for your current 7-day window +- A live countdown until each limit resets +- A small native widget that lives directly in the Windows taskbar +- Right-click options for refresh, update frequency, language, startup, and updates -- **5h** — Session usage (5-hour rolling window) -- **7d** — Weekly usage (7-day rolling window) +## Who This Is For -Each bar shows the current utilization percentage and a countdown until the rate limit resets. +This app is for Windows users who already have **Claude Code (CLI or App) installed and signed in**. -## How it works - -1. Reads your Claude OAuth token from `~/.claude/.credentials.json`, or from `~/.claude/.credentials.json` inside an installed WSL distro if the Windows file is missing or expired (automatically refreshes expired tokens via the matching Claude CLI) -2. Queries the dedicated Anthropic OAuth usage endpoint (`/api/oauth/usage`) for utilization data -3. Falls back to the Messages API with rate limit header parsing (`anthropic-ratelimit-unified-*`) if the usage endpoint is unavailable -4. Renders the widget using Win32 GDI, embedded as a child window of the taskbar -5. Polls every 15 minutes by default (adjustable via context menu) and updates countdown timers between polls - -The widget automatically detects dark/light mode from Windows system settings. You can drag the left divider to reposition the widget along the taskbar. Settings (position and poll frequency) are persisted to `%APPDATA%\ClaudeCodeUsageMonitor\settings.json`. +It works best if you want a simple "how close am I to the limit?" display that is always visible. ## Requirements -- Windows 10/11 -- [Rust toolchain](https://rustup.rs/) (MSVC target) -- An active Claude Pro/Team subscription with OAuth credentials stored by [Claude Code](https://docs.anthropic.com/en/docs/claude-code) +- Windows 10 or Windows 11 +- Claude Code (CLI or App) installed and authenticated -If you use Claude Code inside WSL2, keep `claude` installed and authenticated in that distro. The monitor will scan installed WSL distros and use the first accessible non-expired credential set it finds. +If you use Claude Code through WSL, that is supported too. The monitor can read your Claude Code credentials from Windows or from your WSL environment. -## Building +## Install -```bash -cargo build --release +For now, download the latest `claude-code-usage-monitor.exe` from the [Releases](../../releases) page and run it. + +WinGet support is on the way and currently waiting on final approval. When that is live, installation will be a one-liner. + +Planned command: + +```powershell +winget install CodeZeno.ClaudeCodeUsageMonitor ``` -The binary will be at `target/release/claude-code-usage-monitor.exe`. +## Use -## Usage +Run the app and it will appear in your taskbar. -Run the executable — the widget appears in your taskbar. +- Drag the left divider to move it +- Right-click for refresh, update frequency, start with Windows, reset position, language, updates, and exit -- **Drag** the left divider to reposition the widget along the taskbar -- **Right-click** for a context menu with **Refresh**, **Update Frequency**, **Settings** (Start with Windows, Reset Position), and **Exit** -- Installations managed by WinGet defer upgrades to `winget upgrade` instead of replacing the executable in place +Settings are saved to: -## Project structure - -``` -src/ -├── main.rs # Entry point -├── models.rs # UsageData / UsageSection types -├── poller.rs # API polling, header parsing, formatting -├── window.rs # Win32 window, rendering, message loop -├── native_interop.rs # Win32 helper functions (taskbar, colors, etc.) -└── theme.rs # Dark/light mode detection via registry +```text +%APPDATA%\ClaudeCodeUsageMonitor\settings.json ``` -## Releases +## Account Support -Pre-built Windows executables are available on the [Releases](../../releases) page. Download `claude-code-usage-monitor.exe` and run it directly — no Rust toolchain required. +This app works with the same account types that Claude Code itself supports. -After the GitHub Release is published, the release workflow also attempts to submit a WinGet manifest update for `CodeZeno.ClaudeCodeUsageMonitor`. +As of **March 19, 2026**, Anthropic's Claude Code setup documentation says: -- Configure a classic PAT as the `WINGETCREATE_GITHUB_TOKEN` repository secret with `public_repo` scope so `wingetcreate` can submit to `microsoft/winget-pkgs` -- The first WinGet submission still needs to be created manually; after the package exists, later tagged releases can update it automatically +- **Supported:** Pro, Max, Teams, Enterprise, and Console accounts +- **Not supported:** the free Claude.ai plan + +If Anthropic changes Claude Code availability in the future, this app should follow whatever Claude Code supports, as long as the usage data remains exposed through the same authenticated endpoints. + +## Privacy And Security + +This project is **open source**, so you can inspect exactly what it does. + +What the app reads: + +- Your local Claude Code OAuth credentials from `~/.claude/.credentials.json` +- If needed, the same credentials file inside an installed WSL distro + +What the app sends over the network: + +- Requests to Anthropic's Claude endpoints to read your usage and rate-limit information +- Requests to GitHub only if you use the app's update check / self-update feature + +What the app stores locally: + +- Widget position +- Polling frequency +- Language preference + +What it does **not** do: + +- It does not send your credentials to any other server +- It does not use a separate backend service +- It does not collect analytics or telemetry +- It does not upload your project files + +Notes: + +- If your Claude Code token is expired, the app may ask the local Claude CLI to refresh it in the background +- Portable installs can update themselves by downloading the latest release from this repository + +## How It Works + +The monitor: + +1. Finds your Claude Code login credentials +2. Reads your current usage from Anthropic +3. Shows the result directly in the Windows taskbar +4. Refreshes periodically in the background + +If the newer usage endpoint is unavailable, it can fall back to reading the rate-limit headers returned by Claude's Messages API. + +## Open Source + +This project is licensed under MIT. + +If you want to inspect the behavior or audit the code, everything is in this repository.