clawd-usage-winwidget

A tiny floating window + tray icon for Windows that shows how much of your Claude
plan limits you've used — the same numbers as /usage in Claude Code, refreshed
every minute. And a pixel Clawd who lives in it and reacts to what your sessions
are doing.

English · Русский

• Official numbers only. Percentages come from claude -p "/usage" — the
  slash command runs headless, talks to Anthropic with your existing login and
  does not call the model or spend tokens.
• No dependencies. Plain Windows PowerShell 5.1 + WPF, which ship with
  Windows. No Node, no npm, no installer. You only need Claude Code itself.
• Clawd. The crab from Claude Code's welcome screen, built from the same block
  glyphs and with the same animations. He sleeps when nothing runs, runs around
  when a session works, waves when a session is waiting for you, sweats near the
  limit and lies belly-up when it's used up.

Install

Requirements: Windows 10/11 and Claude Code
installed and logged in (claude on PATH).

git clone https://github.com/Enhed/clawd-usage-winwidget.git

or download the ZIP and unpack it anywhere. Then double-click start-widget.vbs
(it starts the widget silently, without a console window).

Start with Windows — run once in PowerShell from the widget folder:

$a = New-ScheduledTaskAction -Execute "wscript.exe" -Argument "`"$PWD\start-widget.vbs`""
$t = New-ScheduledTaskTrigger -AtLogOn
Register-ScheduledTask -TaskName "clawd usage widget" -Action $a -Trigger $t -RunLevel Limited

Only one copy runs at a time, so a manual start next to autostart is harmless.

Windows hides new tray icons in the overflow (^). To keep it visible:
Settings → Personalization → Taskbar → Other system tray icons → clawd-usage-winwidget.

What it shows

• Big number — current session (the 5-hour window), straight from the server.
  The bar goes green → yellow (60%) → red (85%).
• resets in 3h 03m — time until the window resets, from the exact reset time
  in /usage.
• WEEK — weekly limit and time to reset. FABLE · WEEK — the separate
  weekly Fable limit; hidden if /usage doesn't report it.
• SESSIONS — how many Claude Code sessions are running, how many are
  working and how many are waiting for you. Hover for the list: ▶ working,
  ? waiting (permission, question, dialog — what exactly is in brackets),
  ○ idle, plus the folder. Handy for catching a forgotten agent quietly
  burning your limit.
• Service status — green "All Claude systems operational", or yellow/red
  with the active incident and affected components. Click opens
  status.claude.com.
• Tray icon — the same percentage as a colored number; the tooltip adds the
  week and Fable.
• Bottom line — your plan and account email (red "not logged in" if auth
  expired) and the time of the last /usage answer, marked "stale" if it's old.

The ▾ in the header expands details (remembered between runs):

• LAST 24 HOURS / LAST 7 DAYS — requests, sessions and the "What's
  contributing to your limits usage?" breakdown from /usage: share on large
  context, always-on context, subagent-heavy sessions, top MCP servers, skills
  and subagents. Claude Code itself calls this approximate and counts only this
  computer.
• Version — your Claude Code version. If a newer one is out the line turns
  yellow: hover for the official CHANGELOG between your version and the latest,
  click to run claude update in a separate window; otherwise a click opens
  Claude Code's changelog. Next to it is the widget's own version: hover for what's
  new in it, click for its CHANGELOG.md on GitHub.

Left-click the tray icon to show/hide the window; right-click for the menu:
refresh, larger/smaller, look the computer over, open config, language, Clawd's session, exit. Drag the window anywhere —
the position is saved.

Clawd

No Claude Code running — burrows into the sand and sleeps	Click him — a random Claude Code animation and a heart
Session limit used up — belly-up; click and his soul floats out	The 5-hour window resets — celebration and confetti
Hearts are his health — the session limit left	The sky follows real time of day and live weather

The three hearts in the header are his health, tamagotchi-style: how much of the
session limit is left. Each half-heart is about 16.7%; zero hearts only at 100%.
Health changes how he behaves on top of everything above — full of energy he
walks faster and hops, tired he yawns and slows down, barely alive he staggers,
sweats and sometimes trips over.

Right-click Clawd for developer mode: force any state, play any animation, set
the hearts, pick time of day and weather, or play everything as a demo.
"Auto" goes back to live data.

Sky

Behind the numbers there's a faint sky that fades into the window edges. It
follows real sunrise and sunset for your location: the sun moves along an arc,
at night there's the moon in its actual phase and twinkling stars. Weather adds
clouds drifting with the wind, drizzle, rain, showers, snow (that settles under
Clawd's feet), fog and thunderstorms. Hover for city, temperature, weather, wind,
sunrise and sunset.

Weather comes from Open-Meteo, falling back to
met.no where Open-Meteo is blocked; both need no key.
Location is looked up once per run by IP via ipwho.is — set
weatherLat / weatherLon to skip that. Without network the sky still follows
the clock. Turn it off with showSky.

Clawd's panel: tips and chat

An icon in the header opens a panel beside the widget; it stays open until you
close it with the cross or the icon, and stays on top only if the widget does
(topmost). The icon tells what's waiting: a bell — a
reminder went off, a blue chat — Clawd answered, a lamp with a number — tips
(yellow if urgent), a grey chat — nothing, just talk.

Tips. Every half hour Clawd quietly looks the computer over:

• drives running out of space, and how much sits in Temp, Downloads, the Recycle
  Bin, crash dumps and npm / pip / Yarn / scoop caches;
• new entries in autostart (what was there on the first run is taken as known);
• apps not started for 90+ days — by Windows' own record of launches from Start,
  the taskbar and Explorer; apps in PATH or run as services count as used;
• a restart Windows Update is waiting for, a long uptime, a program eating lots of
  memory or keeping the CPU busy two checks in a row.

Each tip links to the right place and has Do it (Clawd answers with a script
to approve), Refine (your next message goes to him with the tip, e.g. "all
but scoop") and Dismiss; it comes back after a
while if it's still true (a day; a month for unused apps). The check is local and
read-only — no network, no tokens. "Look the computer over now" in the tray menu
runs it right away. Turn it off with showAdvisor.

Chat. Ask Clawd anything about the computer, answer a tip ("clean it all up,
but leave Redis alone") or ask for a reminder ("on Monday at 10 remind me to call
the client", "in 20 minutes — hang the laundry"). Each message is a headless
claude -p call in a conversation of its own (your Claude Code sessions are not
touched), with the current tips, time and reminders attached. Clawd may look
around but can't change anything himself: no write tools, MCP servers off, only
read-only commands allowed. A change comes as a script you see in full, with
Run, Refine (write what to change — the script is replaced) and Not
now. Reminders are kept by the widget and fire on time with a card to
put them off, a bell in the header and a hop from Clawd — even with the panel
closed. The chat uses your plan's limits; the model is chatModel (Sonnet by
default), showChat turns it off.

Reminders and lists. A reminder that goes off shows as a card in the
bottom-right corner, like a phone notification: put it off — +15m, +1h, +3h,
tomorrow 9:00 or any time — or mark it done; it waits until you answer. The panel has three tabs: Chat, Reminders and Lists.
Reminders shows what's coming (Change, +1 hour, Delete) and a form to add one:
the "when" field understands 18:30, tomorrow 10, +20m, mon 9:00,
19.10 14:00 and shows what it made of it. Lists keeps shopping and any other
lists with checkboxes — add several items at once with commas, tick them off,
remove the ticked ones, start a new list with "+". Both are plain files in Clawd's
home, so the chat ("add milk to shopping") and Clawd on your phone ("what do I need
to buy?") work with the same ones.

Clawd's home and his own session. The chat works in Clawd's home folder
(clawdHome). Reminders are plain files there (lists too, in lists\) —
reminders\2026-11\2026-11-16 10-00 Pay the taxes.md with an at: line — so
anyone can make one: the chat, Clawd's session, or you by hand; fired ones move to
reminders\done. After each check the tips are written to tips.md there. With
clawdSession the widget also keeps Clawd's own interactive Claude Code session
running in that folder with Remote Control — talk to him from the Claude app on
your phone: he reads tips.md, makes reminders and keeps notes in the same home.
He is told about all this by clawd-session-prompt.md. While that session is
idle Clawd can still fall asleep; when you talk to him he runs around.

The panel and the phone are two conversations with one Clawd: the panel shows the
phone conversation in the same feed (marked "Remote Control"), its chat gets the
latest part of it as context, and the panel's conversation is written to
chat-log.md in the home for the phone session to read. "+" in the panel starts
a new conversation there and hides the phone conversation so far; on the phone
/clear starts a new one in the same Remote Control entry, and the feed follows.

Where the data comes from

/usage takes about two seconds, so it runs asynchronously and the window never
freezes. If it doesn't answer, the widget keeps the last numbers and marks them
stale.

Don't run claude -p "/usage" by hand from Git Bash: MSYS rewrites /usage
into a path (C:/Program Files/Git/usage) and the prompt goes to the model,
spending tokens. PowerShell and cmd are fine.

config.json

Created next to the script on first save; open it from the tray menu. Changes
are picked up on the fly, no restart needed.

Troubleshooting

Errors in the update loop never crash the widget: the bottom-right corner shows
"error" and details go to widget-error.log next to the script.

If you edit the scripts: .ps1 files must stay UTF-8 with BOM — without it
Windows PowerShell 5.1 reads them as ANSI and breaks on non-ASCII text. Syntax
check:

foreach ($f in @('.\widget.ps1') + (Get-ChildItem .\lib\*.ps1).FullName) {
    $err = $null
    [void][System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path $f), [ref]$null, [ref]$err)
    if ($err) { $f; $err }
}

How it's built

widget.ps1 is the entry point: single instance, loads the modules from lib\
and runs the WPF loop. The window layout is in widget.xaml. Modules are
dot-sourced into one shared script scope in a fixed order; each may rely on the
ones loaded before it. All UI text lives in lib\i18n.ps1 — adding a language
is one more table there.

tools/ holds the recorder that made the GIFs in this README: it boots the
widget with scripted fake data and renders frames straight from WPF. It needs
ffmpeg and Pillow; the widget itself doesn't.

License

MIT

Not affiliated with Anthropic. Clawd and Claude are Anthropic's.