From 6494740fd19d8a09185f60a104eab1a1a18d351c Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Tue, 27 Oct 2026 17:20:26 +0700 Subject: [PATCH] docs: tighten the README Merge the overlapping feature, audience, requirements and usage sections, give updates their own section, fold the file tables into one, and drop the v0.5.0 migration notes. --- README.md | 381 +++++++++++++++++------------------------------------- 1 file changed, 122 insertions(+), 259 deletions(-) diff --git a/README.md b/README.md index b9428b5..93d4b3e 100644 --- a/README.md +++ b/README.md @@ -4,297 +4,160 @@ # Usage Monitor -A floating, draggable circular bubble that shows your Claude Code and/or -Codex usage on Windows and Linux — inspired by the floating "memory boost -ball" UX of 360 Security and IObit Advanced SystemCare. +A floating, see-through bubble that shows how much of your Claude Code and +Codex limits you have used, on Windows and Linux x86_64. Linux ARM64 and macOS +are not supported yet; see [ROADMAP.md](ROADMAP.md). -Drop it anywhere on screen, drag it around, snap it to a monitor edge, -left-click for a panel with both your 5-hour and 7-day windows, right-click -for the menu. +## Features -Linux ARM64 and macOS are not supported yet; see [ROADMAP.md](ROADMAP.md). - -## Acknowledgements - -Inspired by [CodeZeno/Claude-Code-Usage-Monitor](https://github.com/CodeZeno/Claude-Code-Usage-Monitor), -which solves the same "how close am I to the Claude Code limit?" problem -with a horizontal taskbar widget. This project takes the UX in a different -direction — a floating, draggable circular bubble that the user can place -anywhere on screen — and is a clean-room implementation: the HTTP client, -provider polling, credential discovery, tray rendering, and -self-updater are all written from scratch against the same public APIs -(Anthropic, ChatGPT, GitHub Releases). - -## What you get - -- A see-through floating bubble: a round head showing your current 5-hour - Claude Code or Codex usage as a percentage and a colored progress ring, - with a slimmer tail holding the 7-day usage and reset bars -- Drag anywhere — the bubble snaps to monitor work-area edges when - released -- Resize with `Ctrl + MouseWheel` on the bubble, or use **Controls** → - **Make smaller / Make larger / Reset size** from the right-click menu - (140–360 logical pixels) -- Left-click the bubble for an expanded panel with both **5h** and **7d** - bars plus reset countdowns -- Right-click for refresh, displayed providers, update frequency, startup, - **Reset position**, updates, **Show widget**, **Click-through**, - **Restart** and **Exit** -- A system tray icon per enabled provider, with a usage badge -- Desktop notifications when usage crosses a threshold, when a sign-in - expires and after an update was applied -- Auto-hide when a fullscreen app is in the foreground (games, video, - presentations) — reappears when you leave fullscreen -- Bubbles stay above other always-on-top windows, such as chat - notifications: on Windows a bubble goes back on top the moment another - app shows such a window over it, and on every platform shown bubbles are - put back on top every minute, so nothing can keep them covered or hidden - -## Who this is for - -Windows 10/11 and Linux x86_64 users who already have **Claude Code (CLI or -App) installed and signed in** on the same machine. Codex support is -optional — install and sign in to the Codex CLI, then enable Codex from the -right-click **Providers** menu. +- **The bubble:** a round head with your 5-hour usage and a progress ring, + and a tail with the 7-day usage and time to reset. Left-click it for a + panel with both windows and their countdowns. +- **Place it anywhere:** drag it, and it snaps to a screen edge when you let + go near one. Resize it with `Ctrl` + mouse wheel. +- **Always on top:** it stays above other windows, chat notifications + included, and hides while a fullscreen app (a game, a video, slides) is + in front. +- **Click-through:** an option to let clicks pass through the bubble to the + window below. +- **One bubble per provider:** Claude Code is on by default; Codex is + optional. +- **Tray and alerts:** a tray icon with a usage badge per provider, and + desktop notifications when usage crosses a threshold or a sign-in expires. +- **Updates itself:** new releases install automatically. ## Requirements -- Windows 10 or Windows 11, or Linux x86_64 (see below) -- Claude Code (CLI or App) installed and authenticated -- The `claude` CLI, for automatic token refresh. The app looks for it on - `PATH`, and on Linux also in `~/.local/bin` and `~/.claude/local`. Without - it an expired sign-in is not refreshed and you have to sign in again. -- Optional: Codex CLI installed and authenticated, if you want Codex usage. - Its token is refreshed through the `codex` CLI, found the same way. - -### Windows - -The app draws its windows with the Microsoft Edge **WebView2 runtime**. -Windows 11 ships it, and most up-to-date Windows 10 machines already have it. -If it is missing, the app shows a message with the download link and exits; -install the -[Evergreen WebView2 runtime](https://developer.microsoft.com/microsoft-edge/webview2/) -and start the app again. - -### Linux - -- **Runtime libraries:** WebKitGTK 4.1 (`libwebkit2gtk-4.1-0` on - Debian/Ubuntu) and, for the tray icons, `libayatana-appindicator3-1`. - The `.deb` pulls these in. Without an AppIndicator library the app runs - without tray icons. -- **A compositing window manager.** The bubble is a transparent window; - without a compositor its corners are drawn opaque. -- **X11 is the supported session.** Under Wayland the app runs through - Xwayland, where positioning, snapping and always-on-top work. Without - Xwayland (or with `GDK_BACKEND=wayland` set) the bubbles still show, but - they cannot be positioned, snapped, kept on top or saved where you drop - them. -- **Tray limits:** Linux tray icons (AppIndicator) only open the menu. They - show no tooltip, and a left click does not toggle the bubble; use the - menu instead. +- Windows 10/11, or Linux x86_64. +- Claude Code (CLI or app), installed and signed in. The `claude` CLI must + be on `PATH` (on Linux, `~/.local/bin` and `~/.claude/local` work too) so + the app can refresh an expired sign-in. +- For Codex: the Codex CLI, installed and signed in. +- **Windows:** the + [WebView2 runtime](https://developer.microsoft.com/microsoft-edge/webview2/). + Windows 11 and most up-to-date Windows 10 machines have it; if not, the + app tells you and exits. +- **Linux:** + - WebKitGTK 4.1 and `libayatana-appindicator3-1` for the tray icons. The + `.deb` installs both. + - A compositing window manager, or the bubble's corners are drawn + opaque. + - An X11 session. Under Wayland the app runs through Xwayland. Without + Xwayland the bubbles show, but cannot be positioned, snapped or kept on + top. ## Install -### Windows +Download from the +[latest release](https://github.com/tiennm99/usage-monitor/releases/latest). -Grab `usage-monitor.exe` from the -[Releases page](https://github.com/tiennm99/usage-monitor/releases/latest). -Put it in a folder of its own that you can write to (e.g. -`%LOCALAPPDATA%\UsageMonitor\`) and run it. The app is portable: it keeps -`settings.json` next to the exe, so moving the folder keeps your settings. It -updates itself from the same Releases feed: when a check finds a new -release, it installs it and restarts on its own, with no click needed. +- **Windows:** `usage-monitor.exe`. Put it in a folder you can write to, + such as `%LOCALAPPDATA%\UsageMonitor\`, and run it. The exe is unsigned: + when SmartScreen warns, click **More info** → **Run anyway**. +- **Linux AppImage:** `usage-monitor_X.Y.Z_amd64.AppImage`. Put it in a + folder you can write to, run `chmod +x` on it, and run it. +- **Linux .deb:** `sudo apt install ./usage-monitor_X.Y.Z_amd64.deb`. -**First-run note:** the binary is unsigned, so SmartScreen will show -"Windows protected your PC". Click **More info** → **Run anyway**. Code -signing is on the roadmap. +The exe and the AppImage are portable: they keep `settings.json` next to +themselves. -### Linux x86_64 +## Use -From the same -[Releases page](https://github.com/tiennm99/usage-monitor/releases/latest), -pick one: +- **Left-click** the bubble for the details panel. +- **Right-click** the bubble or the tray icon for the menu: + - **Refresh** + - **Update frequency:** how often usage is fetched. + - **Providers:** which bubbles to show. + - **Settings:** start at login, **Reset position**, **Check for updates** + and the **Auto-update check** interval. + - **Controls:** resize. + - **Show widget** + - **Click-through** + - **Restart** and **Exit** +- **Tray icon:** a left click shows or hides the bubbles. On Linux any click + opens the menu, and there is no tooltip. +- **With click-through on**, the bubbles ignore the mouse. Turn it off from + the tray menu. -- `usage-monitor_X.Y.Z_amd64.AppImage`: make it executable - (`chmod +x`) and run it. Like the Windows exe it is portable and keeps - `settings.json` next to the AppImage file, so give it a folder you can - write to. The AppImage updates itself in place, the same way. If you turned on "Start - at login" in v0.6.0 or earlier and the AppImage path contains a space, - turn it off and on again once: those releases wrote the path unquoted, - so the app never started at login. -- `usage-monitor_X.Y.Z_amd64.deb`: install it with - `sudo apt install ./usage-monitor_X.Y.Z_amd64.deb`. The app - still checks for updates, but installing one is left to you: download the - new `.deb` and install it the same way. +Timers follow your local clock. Every 5 minutes means :00, :05, :10 and so +on; hourly means the top of the hour, daily means midnight, and weekly means +Monday at midnight. -### Build from source +### Updates -Prerequisites: the [Rust toolchain](https://www.rust-lang.org/tools/install) -and [Node.js](https://nodejs.org/) with npm. The Tauri CLI is a local dev -dependency, so `npm ci` installs it. +The app checks GitHub Releases on the **Auto-update check** schedule +(hourly by default). At launch it checks only if a scheduled time has passed +since the last check. A failed check is retried after 1, 2, 4… minutes, but +never later than the next scheduled time. -On Windows: +When a check finds a new release, the exe and the AppImage install it and +restart on their own. The `.deb` only tells you; install the new `.deb` the +same way you installed the first. -```powershell -git clone https://github.com/tiennm99/usage-monitor -cd usage-monitor -npm ci -npm run tauri build -- --no-bundle -``` +## Files and diagnostics -The binary lands at `target\release\usage-monitor.exe`. +Run with `--diagnose` to write a log, which is cleared on each start. -On Linux x86_64, install the build dependencies first (Debian/Ubuntu): +| What | Windows | Linux | +|------|---------|-------| +| Log (`--diagnose`) | `%TEMP%\usage-monitor.log` | `~/.local/state/usage-monitor/usage-monitor.log` | +| Settings | `settings.json` next to the exe | next to the AppImage; for the `.deb`, `~/.config/UsageMonitor/settings.json` | +| Update downloads, `update-error.log` | `%LOCALAPPDATA%\UsageMonitor\updates\` | `~/.local/share/UsageMonitor/updates/` | +| Web view cache | `%LOCALAPPDATA%\io.github.tiennm99.usagemonitor\` | `~/.local/share/io.github.tiennm99.usagemonitor/` | + +On Linux the `XDG_*` variables move these folders when they are set. On +Windows the app also writes `%LOCALAPPDATA%\UsageMonitor\icon.png` and an +`HKCU\Software\Classes\AppUserModelId` entry, which notifications from a +portable exe need. + +## Privacy + +- **Reads:** your Claude Code credentials (`~/.claude/.credentials.json`) + and, with Codex on, your Codex credentials (`$CODEX_HOME/auth.json` or + `~/.codex/auth.json`). +- **Sends:** usage requests to Anthropic and, with Codex on, to ChatGPT, + plus update checks to GitHub Releases. Nothing else: no analytics, no + backend, and no credentials sent to any third party. +- **Runs:** when a sign-in has expired, `claude -p .` or `codex exec .` + runs hidden in the temp folder, so the CLI refreshes its token. Codex runs + with `--skip-git-repo-check` and a read-only sandbox. Each run sends one + tiny prompt, which counts toward your usage. +- **Stores:** bubble positions and size, the menu choices, and the time of + the last update check. + +## Build from source + +You need [Rust](https://www.rust-lang.org/tools/install) and +[Node.js](https://nodejs.org/). On Debian/Ubuntu, install the build +dependencies first: ```bash sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential curl wget file \ libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev +``` + +Then: + +```bash git clone https://github.com/tiennm99/usage-monitor cd usage-monitor npm ci npm run tauri build -- --no-bundle ``` -The binary lands at `target/release/usage-monitor`. To build the -`.deb` and AppImage instead, also install `patchelf` (the AppImage needs it) -and run `npm run tauri build -- --bundles deb,appimage`; they land under -`target/release/bundle/`. - -Local builds carry no updater signature (`createUpdaterArtifacts` is off in -`tauri.conf.json`), so they cannot be published as an update. Only the -release workflow signs builds; see +The binary lands in `target/release/`. For the `.deb` and AppImage, install +`patchelf` and run `npm run tauri build -- --bundles deb,appimage` instead. +Local builds are unsigned, so they can't be published as updates; see [docs/release-process.md](docs/release-process.md). -## Use +## Acknowledgements -Run the app. The bubble appears near the bottom-right corner of your -primary monitor on first launch. Drag it where you want it, release to snap -to the nearest edge if you let go close to one. - -- **Left-click** the bubble to open the expanded panel (5h + 7d + countdowns) -- **Update frequency** sets how often usage is fetched. Fetches follow - your local clock: every 5 minutes means :00, :05, :10 and so on, and - every hour means the top of the hour -- **Right-click** for **Refresh**, **Update frequency**, **Providers**, - **Settings**, **Controls**, **Show widget**, **Click-through**, - **Restart** and **Exit**. - **Settings** holds "Start with Windows" ("Start at login" on Linux), - **Reset position**, a manual **Check for updates** and the - **Auto-update check** interval (Disabled / Hourly / Daily / Weekly) -- **Drag** anywhere — it floats on top of all other windows -- **Ctrl + MouseWheel** on the bubble, or **Controls** in the right-click - menu, to resize it -- **Tray icon:** left-click toggles the bubble visibility, right-click opens - the same menu (on Linux, any click opens the menu) -- **Click-through:** when checked, the bubbles ignore the mouse, so clicks - reach the windows underneath. You can't drag, resize or right-click a - bubble then; uncheck it from the tray icon's menu - -### Providers - -Use the right-click **Providers** menu to choose what is shown: - -- **Claude Code** is enabled by default -- **Codex** can be enabled alongside Claude Code or shown by itself - -When multiple providers are shown, each gets its own bubble that you can position -independently. - -### Changes from the v0.5.0 Windows build - -The app moved from a hand-written Win32 UI to Tauri. Most behaviour is the -same; these differences are visible: - -- The transparent corners around the round bubble no longer pass clicks - through to the window below; they just ignore clicks. -- Alerts are Windows toast notifications instead of tray balloons, so they - no longer use a warning or info icon. -- Proxy auto-configuration (PAC scripts and WPAD) is no longer used. A - static system proxy, its bypass list and the `HTTPS_PROXY`-style - environment variables still are, including a SOCKS `ALL_PROXY` such as - `socks5h://127.0.0.1:7890`, for usage requests and updates alike. -- Only one copy runs per signed-in user session, instead of one per machine. - -## Diagnostics - -```text -usage-monitor.exe --diagnose # Windows -usage-monitor --diagnose # Linux .deb (pass the same flag to the AppImage) -``` - -This writes a log file, truncated on each start, to: - -| OS | Log file | -|----|----------| -| Windows | `%TEMP%\usage-monitor.log` | -| Linux | `$XDG_STATE_HOME/usage-monitor/usage-monitor.log`, usually `~/.local/state/usage-monitor/usage-monitor.log` (readable by your user only) | - -Settings are saved to: - -| OS | Settings file | -|----|---------------| -| Windows | `settings.json` next to `usage-monitor.exe` | -| Linux AppImage | `settings.json` next to the `.AppImage` file | -| Linux `.deb` | `$XDG_CONFIG_HOME/UsageMonitor/settings.json`, usually `~/.config/UsageMonitor/settings.json` | - -Other files the app writes: - -| What | Windows | Linux | -|------|---------|-------| -| Update downloads and `update-error.log` | `%LOCALAPPDATA%\UsageMonitor\updates\` | `~/.local/share/UsageMonitor/updates/` | -| Web view profile (cache, storage) | `%LOCALAPPDATA%\io.github.tiennm99.usagemonitor\` (WebView2) | `~/.local/share/io.github.tiennm99.usagemonitor/` (WebKitGTK) | - -On Windows the app also writes its notification icon to -`%LOCALAPPDATA%\UsageMonitor\icon.png` and registers it under -`HKCU\Software\Classes\AppUserModelId\io.github.tiennm99.usagemonitor`, -which Windows needs to show toasts from a portable exe. - -## Privacy and security - -What the app reads: - -- Your local Claude Code OAuth credentials from `~/.claude/.credentials.json` -- If Codex is enabled, your local Codex credentials from `$CODEX_HOME/auth.json` - or `~/.codex/auth.json` - -What the app sends over the network: - -- Requests to Anthropic's Claude endpoints to read your usage -- Requests to ChatGPT's Codex usage endpoint, if Codex is enabled -- Requests for `latest.json` from GitHub Releases, hourly by default. Checks - run on your local clock: hourly at the top of each hour, daily at - midnight, weekly at midnight on Monday. At launch the app checks only if - such a time passed since its last check. A failed check is retried - sooner, starting after a minute and backing off, but never past the next - scheduled time. Set **Settings** → **Auto-update check** to - **Disabled** in the right-click menu to stop them; **Check for updates** - still works when you click it. - -What the app runs: - -- When a usage request is rejected because the sign-in has expired, the app - runs `claude -p .` for Claude Code and `codex exec .` for Codex, for each - provider that was rejected. They run hidden in the background, so the CLI - refreshes its token. Each run sends one tiny prompt, which counts toward - your usage. The runs use the system temporary folder as their working - folder, and Codex runs with `--skip-git-repo-check` and a read-only - sandbox. - -What the app stores locally: - -- Bubble position(s) per model -- Bubble size -- Whether the bubbles are shown (**Show widget**) -- Whether the bubbles let clicks through (**Click-through**) -- Polling frequency -- Auto-update check interval -- Last update check time -- Displayed provider preferences - -What it does **not** do: send credentials to any third-party server, run a -backend service, collect analytics, upload your project files, or write to -your Codex `auth.json` directly. +Inspired by +[CodeZeno/Claude-Code-Usage-Monitor](https://github.com/CodeZeno/Claude-Code-Usage-Monitor), +a taskbar widget for the same problem, and by the floating "boost ball" of +360 Security and IObit Advanced SystemCare. This is a clean-room +implementation against the same public APIs. ## License -Apache License 2.0 — see [LICENSE](LICENSE). +Apache License 2.0. See [LICENSE](LICENSE).