sanduhr-meters

<p align="center"> <img src="docs/images/icon-512.png" width="160" alt="Sanduhr icon"> </p> <h1 align="center">Sanduhr für Claude</h1> <p align="center"><em>Hourglass for Claude — pace yourself on claude.ai.</em></p> <p align="center"> A native desktop widget that turns your Claude.ai subscription usage into something you can actually pace yourself by — burn-rate projection, pace markers, sparkline trends, and five hand-tuned glass themes. </p> <p align="center"> <a href="https://github.com/estevanhernandez-stack-ed/Sanduhr_f-r_Claude/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/estevanhernandez-stack-ed/Sanduhr_f-r_Claude?label=release"></a> <a href="https://github.com/estevanhernandez-stack-ed/Sanduhr_f-r_Claude/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/estevanhernandez-stack-ed/Sanduhr_f-r_Claude?style=flat"></a> <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-4ade80"></a> <a href="https://estevanhernandez-stack-ed.github.io/Sanduhr_f-r_Claude/"><img alt="Landing page" src="https://img.shields.io/badge/landing-page-3bb4d9"></a> </p> <p align="center"> <strong><a href="https://estevanhernandez-stack-ed.github.io/Sanduhr_f-r_Claude/">🌐 Landing page</a></strong> · <strong>macOS</strong> · <strong>Windows 11</strong> · <strong>Python (any OS)</strong> </p> <p align="center"> _{Independent third-party tool. Not affiliated with Anthropic. Requires an active Claude Pro / Team / Enterprise subscription.} </p>

---

Install

macOS — native SwiftUI

Via Homebrew (recommended):

brew tap estevanhernandez-stack-ed/tap
brew install --cask sanduhr

Via DMG: download the latest Sanduhr.dmg from Releases and drag to Applications.

• Developer ID signed + Apple-notarized → no Gatekeeper warnings.
• NSVisualEffectView vibrancy. Credentials live in the macOS Keychain (service com.626labs.sanduhr) on release builds, and in a permissions-restricted file (~/Library/Application Support/Sanduhr/credentials.json, mode 0600) on dev builds — see mac/README.md.
• Auto-updates via Sparkle (24h check interval); brew upgrade --cask sanduhr also works.
• Cask lives in the personal tap. Submission to core Homebrew/homebrew-cask is pending the project's notability bar (90 forks / 90 watchers / 225 stars).
• Requires macOS 14 (Sonoma) or newer.

Windows 10/11 — native .NET 10 / WPF

Via the Microsoft Store (recommended): search Sanduhr für Claude (publisher 626Labs LLC) and install. Store-signed, no SmartScreen prompt, updates arrive through the Store.

Via GitHub Release: download 626Labs.Sanduhr-win-Setup.exe from Releases, click through SmartScreen ("More info → Run anyway"; the installer is unsigned, the Store package is the signed path), and run it. Installs per-user and updates itself from the release feed. A portable zip sits on the same page.

• Win11 Mica glass backdrop (Win10 falls back to solid theme color). Windows 10 1809+ / x64.
• Windows Credential Manager storage (service com.626labs.sanduhr). Uninstall does not clear these entries on either channel — use Sign Out first, or delete them from Credential Manager yourself.
• Full source under windows-dotnet/. The retired Python apps (tkinter v1 and the PySide6 build) were removed on 2026-09-13; they live at tag legacy/python-v2.3.0.
• Step-by-step sign-in, where your data lives, the .msix sideload note, and uninstall behaviour: INSTALL.md.

Claude Code integration — statusline + sanduhr-mcp (Windows 3.4.0+)

Settings ▸ Claude Usage ▸ Install statusline… puts your usage percentages and reset times under the Claude Code prompt of the one home you pick. After each fetch the widget writes %APPDATA%\Sanduhr\snapshot.json; the statusline script and the sanduhr-mcp server (get_usage, get_local_burn_by_project, get_model_usage, get_usage_history, ping, publish_usage, propose_theme) read that file and nothing else that could hold a credential.

• sanduhr-mcp requires widget 3.4.0 or later. Older widgets (the Store's 3.3.0 included) poll and keep history but have no snapshot writer, so the MCP server would read a missing file, or a dead one left behind by a development build. When that happens get_usage and ping answer reason: widget_too_old with the remedy "update it", and serve the widget's latest history point as status: degraded (utilization and reset times only) rather than nothing. widget_not_polling now means exactly that: nothing on the machine has polled in 15 minutes.
• Install it from Settings ▸ Claude Usage ▸ Install MCP server…: pick the one Claude Code home that gets the registration and tick which homes the burn tool may read (none by default). The widget copies the server under %APPDATA%\Sanduhr\mcp\, writes the launcher %APPDATA%\Sanduhr\bin\sanduhr-mcp.cmd, and adds a sanduhr entry to that home's .claude.json with a timestamped backup beside it. New Claude Code sessions pick it up; the widget refreshes the files on every start. Remove MCP server reverts all of it.
• Registering by hand still works, at user scope and never in a project .mcp.json: claude mcp add --scope user sanduhr -- %APPDATA%\Sanduhr\bin\sanduhr-mcp.cmd. Remove it with claude mcp remove sanduhr. Check the pairing any time with the ping tool: it reports the widget version that wrote the snapshot against the 3.4.0 floor.
• Theme Studio. Settings ▸ Themes ▸ Studio edits the fourteen color tokens and two dials with the widget as the live preview, lint findings as you type, Save & apply, Revert, and Copy JSON. Start from any theme.
• Themes from the terminal. With the MCP server installed, ask Claude Code for a theme ("make me a theme from this album cover") and it calls propose_theme: the widget lints the palette (schema plus the design rules in docs/themes/AGENT_PROMPT.md), saves it under %APPDATA%\Sanduhr\themes\, applies it, and tells the agent which theme was active before so you can go back. A rejected palette comes back with the fields to fix; the agent iterates. Settings ▸ Themes shows the same findings for anything you paste.
• Details: docs/superpowers/specs/2026-07-12-statusline-mcp-design.md, docs/PRIVACY.md.

---

Features

Pacing

• Burn-rate projection — "At current pace, expires in 3d 21h" warns before you run dry.
• Always-on pace ghost — a vertical tick on every bar showing where pace says usage should be right now. Real fill sits to the left (under pace), at (on pace), or to the right (ahead). No math required.
• Advanced pacing metrics — hover any tier card to reveal Cooldown required (how long at zero usage to get back on pace) and Surplus (burn-rate delta when under pace).
• Horizon sparkline — classic Heer/Tufte 4-band horizon over the last 2 hours. Peaks stack into dense dark regions, lulls wash soft. More information per pixel than a line chart, toggle via the 📊 button.
• Breathing glass — bars pulse softly toward each theme's accent color. Subliminal, not flickery.

Focus

• Deep-work focus timer — swap the tier cards for a digitised 31×31 pixel hourglass that drains in real time. Inline minute picker, zero external deps.
• Cooldown snake game — pure-Qt/pure-SwiftUI snake for when you've burned through your budget and need to kill a few minutes. Persistent high score.

Chrome & themes

• Five hand-tuned themes — Obsidian, Aurora, Ember, Mint, Matrix — plus unlimited user-authored JSON themes via Settings → Themes or by dropping a .json into your platform's themes folder.
• AI-agent theme prompt (docs/themes/AGENT_PROMPT.md) — hand any chat agent a reference image or vibe description and get back a drop-in theme JSON.
• Win11 Mica glass / macOS NSVisualEffectView — real native vibrancy, no Electron, no WebView.
• Edge-drag resize — hover any edge or corner, cursor changes, click-drag. Minimum bounds track your font metrics so text never clips. New geometry persists across launches.

Privacy & control

• OS-native credential storage on Windows — Windows Credential Manager (service com.626labs.sanduhr). Uninstall does not clear these entries on either channel (GitHub .exe or Microsoft Store) — use Sign Out (below) first, or delete the entries from Credential Manager yourself. On macOS, release builds use the Keychain (service com.626labs.sanduhr; dev builds use a 0600 file) — see mac/README.md. Dragging the Mac app to the Trash removes neither: use Settings → Credentials → Sign Out first.
• Multi-account support (Windows v2.2.0+) — track multiple Claude accounts (Personal + Work) in one install. Per-account credentials, per-account history, switch active account from the widget label or Settings → Accounts. Sign-out is account-scoped — the others stay intact.
• 30-day local history (Windows v2.1.0+) — rolling per-account history file in %APPDATA%\Sanduhr\history.{Account}.json. Settings → History shows a stacked per-tier line chart with Week / Month windows + per-account / All-accounts overlay views. Export as CSV to analyze with any agent.
• One-click sign-out — Settings → Credentials → save with an empty sessionKey. Confirmation dialog, then that account's credentials and history are wiped from the OS store. Other accounts left intact.
• Drag-anywhere, pin/unpin, compact mode, full keyboard shortcuts (Ctrl+R, Ctrl+,, Ctrl+D, Ctrl+H).
• No telemetry, no analytics, no ads. One network destination: claude.ai, using your own session cookie. See SECURITY.md for why no data ever comes back to us.

---

Themes

<table> <tr> <td align="center" width="33%"><img src="docs/images/screenshots/theme-obsidian.png" width="260"><br><strong>Obsidian</strong><br>_{deep black · purple accent}</td> <td align="center" width="33%"><img src="docs/images/screenshots/theme-aurora.png" width="260"><br><strong>Aurora</strong><br>_{dark blue · cyan glow}</td> <td align="center" width="33%"><img src="docs/images/screenshots/theme-ember.png" width="260"><br><strong>Ember</strong><br>_{dark red · orange warmth}</td> </tr> <tr> <td align="center" width="33%"><img src="docs/images/screenshots/theme-mint.png" width="260"><br><strong>Mint</strong><br>_{dark green · teal glass}</td> <td align="center" width="33%"><img src="docs/images/screenshots/theme-626-labs.png" width="260"><br><strong>626 Labs</strong><br>_{navy · cyan · magenta}</td> <td align="center" width="33%"><img src="docs/images/screenshots/theme-matrix.png" width="260"><br><strong>Matrix</strong><br>_{phosphor · CRT corners}</td> </tr> </table>

Drop a custom theme JSON into ~/Library/Application Support/Sanduhr/themes/ (macOS) or %APPDATA%\Sanduhr\themes\ (Windows) and it appears in the theme strip on next launch. Template + prompt at docs/themes/.

---

First-run setup

The easy way (Windows 11 native) — no DevTools

Launch Sanduhr and click Sign in to Claude. A secure in-app window opens on the real claude.ai login page; sign in normally (Google, email, or passkey) and Sanduhr captures your session automatically. No DevTools, no copy-paste. Your credentials are stored in the Windows Credential Manager, never in a file.

Session expired? Sanduhr shows Session expired — sign in again with a one-click button that re-authenticates the active account in place — your history is kept and no duplicate account is created. You can also re-authenticate any account from Settings → Accounts.

Manual sessionKey (power-user / Python build)

Prefer to paste the key by hand, or running the cross-platform Python build?

1. Go to claude.ai and sign in.
2. Open DevTools (⌥⌘I on macOS, F12 on Windows).
3. Navigate to Application → Cookies → claude.ai.
4. Copy the value of the sessionKey cookie.
5. Paste it into Sanduhr (Windows native: Settings → Accounts → Add by sessionKey).

Sanduhr hits two claude.ai endpoints — the same ones the settings page uses — to read your usage, and stores the cookie in Windows Credential Manager on Windows or, on macOS, the Keychain (release builds; a permissions-restricted 0600 file on dev builds). Nothing else leaves your machine.

---

Controls

| Action | Effect | |--------|--------| | 🎨 Theme | Open theme picker menu | | ⚙ Settings | Credentials · Themes · Pacing · Help tabs | | 📊 Graph | Cycle sparkline: Classic / Horizon | | ↕ Compact | Toggle compact mode (Ctrl+D) | | ⏳ Focus | Swap tier cards for the deep-work hourglass | | 🐍 Snake | Play the cooldown snake game | | Refresh | Force a data refresh (Ctrl+R) | | Pin / Unpin | Toggle always-on-top | | Drag anywhere | Reposition the widget | | Drag any edge or corner | Resize the widget | | Double-click anywhere | Toggle compact mode | | Right-click | Refresh / Compact / Settings / Quit | | × | Close Sanduhr |

Full keybindings documented in the in-app Settings → Help tab.

---

Docs

• Landing page
• Privacy policy
• Runbook — release, hotfix, rollback
• ADRs — nine architecture decision records
• Threat model — assets, controls, ratings
• Deployment procedure
• Changelog
• Contributing
• Security policy — how to report vulnerabilities, and why no data ever comes back to us

---

Roadmap

Shipped in v2.2.0 (Windows)

• [x] Multi-account support (Personal + Work in one install)
• [x] Per-account history files + aggregated overlay view in Settings → History
• [x] Active-account label in the widget (click to cycle)
• [x] Account-scoped sign-out (other accounts left intact)
• [x] extra_usage tier (API credit spend tracking)

Shipped in v2.1.0 (Windows)

• [x] Historical usage dashboard with CSV export (30-day retention)
• [x] Settings → History tab with stacked per-tier line charts (Week / Month)

Shipped in v2.0.4

• [x] Pace ghost (always-on pace position tick on every bar)
• [x] Horizon sparkline (replaces pulse histogram)
• [x] Breathing glass (subliminal accent pulse)
• [x] Edge-drag resize with dynamic minimum bounds
• [x] Deep-work focus timer with digitised hourglass
• [x] Cooldown snake game
• [x] Advanced pacing metrics (Cooldown required, Surplus)
• [x] One-click sign-out from Settings

Up next

• [x] Microsoft Store listing live (since v3.1.0 on the .NET build)
• [x] Homebrew install available via estevanhernandez-stack-ed/tap (repo)
• [ ] Homebrew cask submission to core Homebrew/homebrew-cask (pending notability bar)
• [ ] winget manifest (pending MS Store cert)
• [ ] Routines daily-quota tracking (Claude Code routines — different endpoint, count-based shape)
• [ ] Real-time mode via local Claude Code log read (alongside the /usage endpoint)
• [ ] Mac parity for v2.1.0 / v2.2.0 features (history, multi-account)
• [ ] Auto-start on boot (native builds)
• [ ] Antigravity (Google Gemini IDE) quota tracking
• [ ] Official Anthropic read-only usage endpoint support (pending Anthropic response)

---

Why "Sanduhr für Claude"?

Sanduhr (ZAHND-oor) is German for "hourglass" — Sand + Uhr (sand clock). Für = "for." You're watching the sand drain on your Claude usage, pacing yourself so you don't run out before the reset.

---

License

MIT — do whatever you want with it. Built by 626Labs LLC (@626Labs-LLC on GitHub).

<p align="center"> _{"Claude" and "claude.ai" are trademarks of Anthropic PBC, used nominatively to describe integration. Sanduhr für Claude is an independent third-party tool.} </p>