ccwatch

Claude Code usage on your Apple Watch.

A tiny Mac daemon polls Anthropic for your live 5-hour and 7-day Claude Code subscription utilization, and an Apple Watch face shows it — animated pixel mascot, dual progress arcs, and complications you can pin to any face.

Splash	Meter	Complications	Smart Stack

Inspired by Clawdmeter by Hermann Björgvin — the Anthropic rate-limit-header technique is theirs. Where Clawdmeter puts it on your desk via ESP32, ccwatch puts it on your wrist.

---

What it shows

• 5-hour session % — your live Claude Code subscription utilization in the rolling 5h window.
• 7-day window % — your usage against the rolling 7-day cap.
• Reset countdowns — minutes until each window resets.
• Tier mood — Clawd's animation gets more frantic as usage climbs (idle → light → moderate → heavy → on fire).

Complication families: circular, corner, rectangular, inline. Stick one on any watch face — Modular, Infograph, X-Large, Smart Stack, whatever.

How it works

[ Mac daemon (ccwatchd) ]
   │  one tiny /v1/messages call per minute
   │  reads "anthropic-ratelimit-unified-{5h,7d}-utilization" headers
   ▼
[ Bonjour-advertised HTTP service on local Wi-Fi ]
   │
   ▼
[ Apple Watch app ]
   │  polls every 60s via NWBrowser + URLSession
   ▼
[ ccwatch face & complications ]

No iPhone runtime. No cloud relay. No iCloud entitlement. Two pieces: a Mac daemon and a Watch app. Same Wi-Fi required between them.

Requirements

• macOS 13+ with Claude Code signed in
• An Apple Watch on watchOS 10+
• An iPhone (only for one-time Watch pairing — not used at runtime)
• A free Apple ID (for sideloading the Watch app)
• Full Xcode (to build + sign the Watch app with your Apple ID)

Install

Easiest: hand this link to your coding agent

If you have Claude Code (or any agent with shell access) open, paste in:

Install ccwatch on my Mac. Follow the playbook at https://github.com/akashbangad/ccwatch/blob/main/install-via-agent.md

The agent reads install-via-agent.md, clones the repo, runs the installer, verifies the daemon is polling, and asks you for only the two things it can't do itself: your Mac password (for sudo) and the macOS Keychain "Always Allow" click that grants the daemon access to your Claude Code OAuth token. Total wall time ~1 min.

Manual install

git clone https://github.com/akashbangad/ccwatch.git
cd ccwatch
./install.sh

This builds ccwatchd via Swift Package Manager, drops it in /usr/local/bin, and registers a launchd agent so it runs at every login. macOS will prompt once for Keychain access — click Always Allow.

You now have ccwatchd running. Check it any time:

launchctl list | grep dev.ccwatch.daemon
tail -F ~/Library/Logs/ccwatchd.log
./scripts/diagnose.sh

Apple Watch app (~5 minutes, one-time)

When install.sh asks "Also install the Apple Watch app?", say yes. You'll need:

• Full Xcode (the script will tell you if it's missing)
• An Apple ID signed into Xcode → Settings → Accounts
• Your iPhone plugged into this Mac (USB or paired wirelessly), and your Apple Watch paired to that iPhone

The script builds, signs (with your free Apple ID), and installs to your watch. On the watch:

Settings → General → VPN & Device Management → tap your Apple ID profile → Trust.

Open ccwatch on the watch. Within ~60 seconds it discovers the Mac and shows live usage.

Set up the weekly auto-resign (highly recommended on free Apple ID)

Free Apple ID certs expire after 7 days, so without this the watch app stops working a week from now. Run:

./scripts/install-resign-agent.sh

Every Sunday at 9 AM your Mac will silently re-sign and re-push the watch app. Watch just needs to be on the same Wi-Fi at that moment — charger overnight at home is enough. Fire-and-forget thereafter.

Skip this only if you have a paid Apple Developer account ($99/yr); paid certs last a year.

Anatomy

ccwatch/
├── daemon/                       Mac daemon (Swift Package executable)
│   ├── Package.swift
│   └── Sources/ccwatchd/
│       ├── main.swift            polling loop, signal handling
│       ├── KeychainReader.swift  reads Claude Code's OAuth token
│       ├── UsagePoller.swift     1-token call + header parsing
│       ├── BonjourServer.swift   _ccwatch._tcp HTTP server
│       └── UsageSnapshot.swift   wire format
├── ClawdShared/                  Swift package — shared types (used by Watch app)
├── ClawdiOS/                     Xcode project — Watch app + complications
│   ├── ClawdWatch Watch App/     SwiftUI views, UsageStore, sprite animator
│   └── ClawdComplications/       four complication families
├── install.sh                    one-command setup
├── scripts/
│   ├── resign-watch.sh           manual re-sign trigger
│   ├── install-resign-agent.sh   set up the weekly resign launchd job
│   └── diagnose.sh               health check (paste output in issues)
├── docs/
│   ├── ARCHITECTURE.md
│   └── XCODE_MIGRATION.md        manual Xcode cleanup steps after `git pull`
└── sprites/
    └── SPEC.md                   how to drop in real pixel art

Honest caveats

These are real and worth knowing before you install:

1. Same-Wi-Fi requirement. The watch finds the Mac via Bonjour on your local network. Different networks → no sync. Watch shows last-known value until reunited.
2. Mac sleeping = stale data. The daemon stops polling when the Mac sleeps. As soon as the Mac wakes, it resumes (within seconds).
3. Anthropic could change the headers. We read anthropic-ratelimit-unified-{5h,7d}-utilization, which Anthropic hasn't documented. If they change them, ccwatch breaks until someone updates the parser. (PRs welcome.)
4. The 7-day cert thing. Free Apple IDs expire signed apps after 7 days. The auto-resign agent handles this transparently as long as your Mac is on and reachable by the watch weekly. If you travel without your Mac for 8+ days, you'll need to re-sign manually when you return.
5. iCloud / cellular Apple Watch. Not yet — that needs the Apple Developer Program ($99/yr) for iCloud entitlements. If this gets enough interest I may pay it and ship a TestFlight build that works everywhere. Until then, same-Wi-Fi is the constraint.

Why this exists

If you use Claude Code professionally, you've felt the rate-limit anxiety: am I close to hitting the wall? When does my session reset? Should I push a big change now or after 4 PM? The data exists in Anthropic's response headers but nobody surfaces it on glanceable hardware.

ccwatch is a glanceable answer.

Contributing

Bug reports, sprite art, Anthropic header fixes, complication designs — all welcome. Open an issue or PR.

Before reporting a bug: please run ./scripts/diagnose.sh and paste the output.

License

MIT — see LICENSE.

Credits

• Clawdmeter — Hermann Björgvin discovered the Anthropic-header trick and built the ESP32 reference design that inspired this.
• claudepix by @amaanbuilds — pixel-art Clawd reference (used in placeholder sprites; replace with your own art).
• The Anthropic team for shipping Claude Code with such generous rate limits that we needed a watch face to track them.