Claude Island 🏝️

Your Claude Code burn rate, live in the iPhone Dynamic Island.

Block cost · token count · $/hr burn · 5-hour limit countdown — with Clawd the mascot keeping watch.

No server. No push notifications. No paid Apple account. A GitHub gist is the entire backend.

---

Why

Claude Code's subscription plans meter usage in 5-hour blocks, but there's no API to check where you stand — the data lives in local logs on your Mac. So when you're deep in a session, the only way to know you're about to hit the limit is... hitting the limit.

Claude Island puts that number where you can't miss it: the Dynamic Island, the lock screen, and a dashboard app.

How it works

┌──────────────────┐    every 5 min     ┌──────────────┐      polls       ┌───────────────┐
│   Claude Code    │ ───  ccusage  ───▶ │ private gist │ ◀─── (ETag) ──── │    iPhone     │
│ logs (~/.claude) │    launchd job     │ (the backend)│                  │ Live Activity │
└──────────────────┘                    └──────────────┘                  └───────────────┘

1. A launchd job on your Mac summarizes Claude Code's local logs with ccusage every 5 minutes and PATCHes one small JSON file in a private gist.
2. The iPhone app polls that gist with a gist-scoped token and renders a Live Activity. ETag conditional requests make unchanged polls free against GitHub's rate limit.

That's the whole system. No accounts, no third-party services, nothing to deploy.

What you get

In the Dynamic Island

🦀 Clawd	the official mascot — hops when fresh data lands, leaps when burn goes hot, flattens asleep when your Mac stops pushing
⭕ Live ring	the 5-hour block, filling in real time around Clawd
🎰 Odometer cost	block cost rolls digit-by-digit on updates, colored by heat (green → orange → red)
⏱ Reset countdown	ticking resets in 1:23:28, always live
📊 Stats row	tokens · $/hr burn · today's total
🔄 Buttons	refresh & stop right in the island (iOS 17+)

In the app

• Current block card — circular cost gauge, tokens, burn rate, projected block cost, model, reset timer
• Burn-rate chart — last ~2 hours, 5-minute samples
• 14-day history — cost/tokens toggle, plus a cumulative spend curve
• Today by model — donut of spend per model (fable vs sonnet vs …)

Extras

• Lock screen card with the same live data
• "Track Claude Usage" Shortcut — start the island from the Action Button or Back Tap without opening the app (iOS 17+)
• Background refresh keeps the island fresh-ish while the app is closed

Setup (~5 minutes)

You need: a Mac running Claude Code, an iPhone, Xcode, and a free Apple ID. node on the Mac (and xcodegen only if you edit project.yml).

1 — GitHub token. github.com/settings/tokens → Generate new token (classic) → check only gist.

2 — Mac bridge.

cd mac-bridge && ./install.sh

Paste the token when asked. It creates the private gist, installs the 5-minute launchd job, and prints the gist ID — copy it. (The runnable copy is installed to ~/.local/share/claude-island-bridge — macOS privacy protection blocks launchd from executing scripts in Desktop/Documents.)

3 — Build the app.

open ClaudeIsland.xcodeproj

• Signing & Capabilities → set your Personal Team on both targets (change the bundle IDs if they collide)
• Plug in the iPhone, enable Developer Mode on it, ⌘R
• First launch: Settings → General → VPN & Device Management → trust your certificate

4 — Phone.

• Settings → Claude Island → allow Live Activities
• In the app: paste the token + gist ID → Save → Track 🏝️

Free Apple ID reality: builds expire after 7 days — plug in and ⌘R to re-sign. A paid account makes it yearly.

Honesty box 📦

• Costs are API-equivalent. ccusage prices your tokens at API list rates. On a subscription you pay flat — read the number as usage intensity, not a bill. (It's still the best proxy for how hard you're hitting the 5-hour block.)
• Updates aren't push. The phone polls: every 30–60 s with the app open, opportunistically (15–60+ min) in the background. The island's refresh button is the guaranteed path. Real-time push needs a server + paid Apple account — deliberately out of scope.
• Mac asleep = stale data. The island shows a 🌙 "Mac asleep?" marker when nothing has been pushed for 20 minutes, instead of pretending to be fresh.

Troubleshooting

Symptom	Fix
🌙 moon in the island	Mac is asleep, or the bridge died — check /tmp/claude-island-bridge.log
Numbers frozen	Open the app or tap the island's ↻ — background refresh is opportunistic by design
401 error	Token expired or missing the gist scope
No burn chart / donut	Burn chart needs 3+ pushes (~15 min); model donut needs iOS 17
Island never appears	Live Activities disabled in Settings → Claude Island
App won't launch after a week	Free-account signing expired — plug in, ⌘R

Uninstall the bridge

launchctl unload ~/Library/LaunchAgents/com.ansh.claudeisland.bridge.plist
rm ~/Library/LaunchAgents/com.ansh.claudeisland.bridge.plist
rm -rf ~/.local/share/claude-island-bridge ~/.config/prisland-bridge

Credits

• Usage parsing by ccusage
• Clawd pixel mascot via LobeHub Icons
• Built with SwiftUI + ActivityKit + Swift Charts. No third-party iOS dependencies.