Usage Dock for Claude Code

A PowerToys Command Palette extension that puts your Claude subscription usage in the Dock.

Unofficial community project. Not affiliated with or endorsed by Anthropic or Microsoft. Claude and Claude Code are trademarks of Anthropic, PBC; they are used here only to say which tool this extension works with.

• In the Dock: the 5-hour session limit, e.g. 🟢 30% 5h · 2h 14m (🟡 from 70%, 🔴 from 90%).
• Click it: all limits (session, weekly, model-scoped such as Fable weekly) with reset countdowns, your plan, and, at the bottom, local token stats.

Where the numbers come from

Data	Source	Scope
Session / weekly / model limits, reset times	GET https://api.anthropic.com/api/oauth/usage, the same endpoint Claude Code's /usage uses	Your account, across claude.ai, desktop, and Claude Code
Plan label	~/.claude/.credentials.json	Local
Tokens by day / model, prompts, sessions	~/.claude/projects/**/*.jsonl transcripts	This PC, Claude Code only

The extension reuses the OAuth token Claude Code already stores. The token goes only into the Authorization header of that one request. It is never logged, written, or refreshed. When it expires the band shows ⚠️ auth, and starting Claude Code once refreshes it.

The usage endpoint is undocumented and may change. It also rate-limits aggressive polling, so the default refresh interval is 5 minutes and 429 responses back off 3 → 6 → 12 → 15 min.

CLAUDE_CONFIG_DIR is honoured if your Claude Code config lives somewhere other than ~/.claude.

Requirements

• Windows 10 19041+ / Windows 11, PowerToys with Command Palette 0.9 or later (Dock support)
• Signed in to Claude Code on this machine (a Pro/Max subscription login)

Installation

1. Turn on the Dock

1. Install or update PowerToys and make sure Command Palette is enabled in PowerToys Settings.
2. Open Command Palette (default Win+Alt+Space) → Settings → Dock (Preview) → turn on Enable Dock.

2. Download

From the latest release download:

• UsageDockDev.cer
• the package for your CPU: UsageDock_<version>_x64.msix (Intel/AMD) or UsageDock_<version>_arm64.msix (Arm, e.g. Snapdragon). Not sure? Run $env:PROCESSOR_ARCHITECTURE in PowerShell: AMD64 → x64, ARM64 → arm64.

3. Trust the certificate (once per machine)

The package is signed with a self-signed certificate, so Windows has to be told to trust it. In PowerShell as Administrator, in the download folder:

Import-Certificate .\UsageDockDev.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople

4. Install

In a normal PowerShell window (or double-click the .msix and choose Install):

Add-AppxPackage .\UsageDock_<version>_x64.msix

5. Show it in the Dock

1. Open Command Palette and run Reload so it picks up the new extension.
2. The Usage Dock band usually appears in the Dock by itself. If it doesn't, search for Usage Dock in Command Palette, open its context menu and run Pin to Dock (choose the Right side to sit next to the system info).
3. Click the band for the detail view. Settings: search Usage Dock → Settings.

Update

Download the newer .msix and run Add-AppxPackage again; the certificate step isn't needed again. Then Reload Command Palette.

Upgrading from 0.1.x ("Claude Usage")

Version 0.2 renamed the extension and changed its package identity and signing certificate, so Windows treats it as a new app. Remove the old one first, then follow steps 3 to 5 with the new files; the refresh-interval setting is not carried over:

Get-AppxPackage ClaudeUsage | Remove-AppxPackage

Uninstall

Get-AppxPackage UsageDock | Remove-AppxPackage
# optional, as Administrator: remove the trusted certificate
Get-ChildItem Cert:\LocalMachine\TrustedPeople | Where-Object Subject -eq 'CN=UsageDockDev' | Remove-Item

Troubleshooting

Symptom	Fix
0x800B0109 / "the root certificate … is not trusted" on install	Step 3 was skipped or not run as Administrator.
0x80073CFB / "a package with the same identity is already installed"	A development build is registered: Get-AppxPackage UsageDock | Remove-AppxPackage, then install again.
Band doesn't appear	Check Enable Dock is on, run Reload, then use Pin to Dock as in step 5.
Band shows ⚠️ auth	The Claude Code sign-in expired. Start Claude Code once (or run claude auth login); the band recovers on the next refresh.
Band shows --% for a long time	No usage data yet: Claude Code must be signed in on this machine with a Pro/Max account.
Clicking the band opens the palette instead of the flyout, or it stops updating	Command Palette host issues, see Known host issues. Reload fixes both.

Settings

Command Palette → Usage Dock → Settings: Refresh interval (1, 2, 5, 10, 15, 30 min; default 5).

Build from source

Needs the .NET 10 SDK. A full Windows SDK / Visual Studio is not required.

dotnet test tests\ClaudeUsage.Tests -p:Platform=x64      # unit tests
.\scripts\dev-deploy.ps1                                 # build + register (Developer Mode on)
.\scripts\dev-deploy.ps1 -Remove                         # unregister

After deploying, run Reload in Command Palette. If the band does not appear by itself, use Pin to Dock (see Installation).

MSIX package

.\scripts\pack.ps1 -Sign        # dist\...\UsageDock_<ver>_x64.msix + dist\UsageDockDev.cer

-Platform ARM64 builds the Arm package. The first -Sign run creates a self-signed CN=UsageDockDev code-signing certificate in Cert:\CurrentUser\My and reuses it afterwards. Install the result as described in Installation.

Back up that certificate with its private key. Without it, later releases can't be signed with the same certificate and every user has to trust a new one:

.\scripts\backup-signing-cert.ps1 -Destination D:\backup   # asks for a password, writes UsageDock-signing.pfx

The icons are generated by python scripts/make-icons.py (needs Pillow).

Layout

src/ClaudeUsage/        Command Palette extension (Dock band, detail page, settings, UsageStore)
src/ClaudeUsage.Core/   Plain .NET library: credentials, API client, parser, transcript scanner, markdown
tests/ClaudeUsage.Tests xUnit tests for Core
scripts/                dev-deploy.ps1, pack.ps1, make-icons.py, backup-signing-cert.ps1

Known host issues

These are Command Palette bugs, not bugs in this extension:

• #50367: after the host releases an idle extension, clicking a band opens the palette instead of the flyout.
• #49688: bands stop repainting after roughly 41 hours of uptime.

Running Reload in Command Palette works around both.

License

MIT. Parts derived from the PowerToys extension template are © Microsoft, MIT; see NOTICE.