claude-usage

KO | EN

gitlite — search

#framework #large-language-models #artificial-intelligence #reactjs #pdf #java #github #react-native #swift #macos

(★ 9)

Native macOS widget showing live Claude Code + OpenAI Codex usage on your desktop

File Explorer

ZIP Download

- clawd.png
- icon.png
- openai.png
- - App.entitlements
  - ClaudeAccountAPI.swift
  - ClaudeAILoginSheet.swift
  - ClaudeKeychain.swift
  - ClaudeUsageApp.swift
  - CodexAccountAPI.swift
  - CodexAuth.swift
  - ContentView.swift
  - Info.plist
  - Refresher.swift
  - SessionCookie.swift
- - CloudUsageProvider.swift
  - CodexUsage.swift
  - Formatters.swift
  - PlanUsage.swift
  - Pricing.swift
  - ProviderStatus.swift
  - SharedContainer.swift
  - SnapshotSync.swift
  - Theme.swift
  - UsageEntry.swift
  - UsageRecord.swift
  - UsageSnapshot.swift
  - UsageStore.swift
- - ClaudeUsageWidget.swift
  - Info.plist
  - Provider.swift
  - Widget.entitlements
.gitignore
build.sh
project.yml
push-watch.sh
README.md
release.sh

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A native widget that shows live usage for **Claude Code** and **OpenAI Codex**
side by side — on your **Mac**, **iPhone**, and **Apple Watch**. See your
session burn, weekly caps, and reset timers at a glance, without opening
claude.ai or chatgpt.com.

The Mac does all the work (fetching usage, scanning local logs) and publishes a
small snapshot to your **private iCloud (CloudKit)**; the iPhone and Watch are
read-only mirrors of that snapshot. So when you're away from your Mac, your
wrist still shows where you stand.

## Features

- **Mac, iPhone, and Apple Watch** — one Mac app feeds a matching iPhone
  Home Screen widget + app and an Apple Watch app + watch-face complications,
  all synced over your private iCloud.
- **Three widget sizes** (Small, Medium, Large) — pick whichever fits your
  taste; all three render Claude and Codex consistently. The Large widget adds
  a 7-day token sparkline.
- **Honest token counts** — totals exclude cache *re-reads* (Claude Code
  re-reads the whole context every turn, which would otherwise balloon the
  number into the billions), so you see real new-token volume.
- **Live data, not local guesses** — pulls real plan usage directly from
  `claude.ai/api/organizations/.../usage` and from
  `chatgpt.com/backend-api/codex/usage`. Refreshes every 5 minutes.
- **Detects what you have installed** — if you only use Claude Code,
  Codex hides itself (and vice versa). No empty placeholders.
- **One-click claude.ai sign-in** — embedded WKWebView grabs your
  `sessionKey` cookie. No copy-pasting cURL.
- **Codex needs zero setup** — auto-reads `~/.codex/auth.json` after you've
  run `codex login` once.
- **Run at login** — toggleable from the host app (uses `SMAppService`).
- **Companion preview pane** — see every widget size + every provider-state
  combination (`Live`, `Both`, `Claude only`, `Codex only`) inside the app
  before adding the widget.

## Requirements

- **macOS 14+** for the Mac app and desktop widgets.
- **Xcode 15+** and [XcodeGen](https://github.com/yonaskolb/XcodeGen)
  (`brew install xcodegen`) to build from source.
- **Claude Code** usage data in `~/.claude` and/or **Codex** usage data in
  `~/.codex`.
- **Claude sign-in** through the app if you want live Claude plan/session
  percentages.
- **`codex login` once** if you want live Codex plan/window percentages.
- **iCloud signed into the same Apple ID** on Mac, iPhone, and Apple Watch if
  you want the iPhone app, iPhone widget, Watch app, or watch-face
  complications.
- **An Apple developer team that can provision iCloud/CloudKit** for physical
  iPhone/watch installs. If Xcode refuses to add the CloudKit capability on a
  free Personal Team, use a paid Apple Developer Program team or remove the
  iOS/watch targets.

## Mac Setup

### Quickest Path: Prebuilt DMG

**[⬇ Download AI-Usage-1.0.1.dmg](https://bgmcuxqagdhdyg6v.public.blob.vercel-storage.com/AI-Usage-1.0.1.dmg)**
(~3 MB)

This is the official binary, signed with my Apple Developer ID certificate
and notarized + stapled by Apple. macOS will open it cleanly with no
Gatekeeper warning, no right-click → Open dance, no `xattr` removals.

1. Download and open the DMG.
2. Drag **AI Usage** to `/Applications`.
3. Launch **AI Usage**. Keep it running at least once so it can refresh data
   and register its WidgetKit extension.
4. In **AI Usage**, sign into Claude if you want Claude plan/session limits.
5. In Terminal, run `codex login` if you want Codex account limits.
6. Open Notification Center → **Edit Widgets** → search **AI Usage** →
   pick Small, Medium, or Large.

If you'd rather not trust a stranger's binary, the build-from-source path
below produces the exact same app from the code in this repo.

### Build the Mac App From Source

```bash
git clone https://github.com/<you>/claude-usage.git
cd claude-usage
xcodegen generate
open ClaudeUsage.xcodeproj
```

Or with no Xcode IDE:

```bash
xcodegen generate
xcodebuild \
  -project ClaudeUsage.xcodeproj \
  -scheme ClaudeUsage \
  -configuration Debug \
  -derivedDataPath ./build \
  CODE_SIGNING_ALLOWED=NO build
open "./build/Build/Products/Debug/AI Usage.app"
```

You can also use the helper:

```bash
./build.sh
open "./build/Build/Products/Debug/AI Usage.app"
```

The Mac app refreshes every 5 minutes. It also refreshes immediately on launch.
Debug logs are written to:

```text
~/Library/Application Support/ClaudeUsage/debug.log
```

Look for `icloud snapshot published` before expecting iPhone/watch surfaces to
show fresh data.

### Build a Signed/Notarized DMG

The `release.sh` helper does the whole signed-DMG flow:

```bash
./release.sh                 # signed .dmg (one-time Gatekeeper warning)
./release.sh --notarize      # signed + notarized + stapled (no warning)
```

First-time notarization setup:

```bash
xcrun notarytool store-credentials ai-usage \
  --apple-id you@example.com \
  --team-id <YOUR_TEAM_ID> \
  --password <APP_SPECIFIC_PW>
```

Generate the app-specific password at [appleid.apple.com](https://appleid.apple.com).

## iPhone And Apple Watch Setup

The Mac app publishes a tiny `UsageSnapshot` to your **private CloudKit
database** at the end of every refresh. The iPhone and Watch apps read that
snapshot directly from iCloud — they never call claude.ai/chatgpt.com or scan
local files (Codex's data only exists on your Mac). They are read-only display
surfaces, so **the data is only as fresh as the last time your Mac synced.**

- **iPhone** — a full app (header, brand rings, plan bars, 7-day token
  sparklines) plus Home Screen widgets in all three sizes.
- **Apple Watch** — a paged app (swipe between Claude and Codex, each a
  full-screen ring + weekly bar + sparkline + reset timers) plus watch-face
  complications: circular gauges for Claude session and Codex 5h, and a
  rectangular "both providers" complication.

### 1. Update Local IDs For Your Apple Account

The repo is currently set up for Marco's developer team and bundle IDs. If you
are building under your own Apple account, edit [`project.yml`](project.yml)
first, then regenerate the Xcode project.

Change these values:

- `DEVELOPMENT_TEAM`: your Apple team ID.
- `options.bundleIdPrefix`: a reverse-DNS prefix you own, for example
  `com.yourname.aiusage`.
- Every `iCloud.com.marcovhv.claudeusage` value: your CloudKit container ID.
- `push-watch.sh` → `WATCH_UDID`: your Apple Watch device identifier.

The watch bundle IDs must keep this shape:

```text
iPhone app:       <prefix>.ios
iPhone widget:    <prefix>.ios.widget
Watch app:        <prefix>.ios.watchkitapp
Watch widget:     <prefix>.ios.watchkitapp.widget
CloudKit:         iCloud.<your-container-name>
```

Keep the watch app embedded in the iPhone app, keep `SKIP_INSTALL: YES` on the
watch target, and do not add `codeSign: true` back to the iPhone target's
`ClaudeUsageWatch` dependency. Those details are what make the companion watch
install path behave like a normal Xcode watch app.

After editing:

```bash
xcodegen generate
open ClaudeUsage.xcodeproj
```

### 2. Provision CloudKit

These targets require the **iCloud (CloudKit)** capability on the App IDs, so
they need a real (non-wildcard) provisioning profile — let Xcode's automatic
signing handle it:

1. Open the generated project in Xcode.
2. Select these targets one by one:
   `ClaudeUsage`, `ClaudeUsageiOS`, `ClaudeUsageiOSWidget`,
   `ClaudeUsageWatch`, and `ClaudeUsageWatchWidget`.
3. In **Signing & Capabilities**, set the same **Team** on all five targets.
4. Add **iCloud** with **CloudKit** enabled to every target that reads or writes
   the snapshot.
5. Use the same CloudKit container on all of them.
6. Build once. Xcode should create managed provisioning profiles for the app,
   widgets, watch app, and watch widget.

The macOS WidgetKit extension does not use App Groups. The Mac host app writes
cache files directly into the widget container because wildcard macOS widget
profiles strip App Group entitlements. iPhone/watch sync uses CloudKit instead.

### 3. Publish The First Snapshot From The Mac

1. Launch the Mac app.
2. Sign into Claude inside the app if needed.
3. Run `codex login` if needed.
4. Wait for the first refresh, or relaunch the app to trigger one immediately.
5. Confirm the debug log contains `icloud snapshot published`.

The iPhone and Watch cannot invent data. They only display the latest snapshot
the Mac published.

### 4. Install The iPhone App

Use Xcode:

1. Connect and unlock the iPhone.
2. Select the **ClaudeUsageiOS** scheme.
3. Select your iPhone as the run destination.
4. Press **Run**.
5. Launch **AI Usage** on the phone and confirm it shows the CloudKit snapshot.

Or build from Terminal:

```bash
xcodebuild \
  -project ClaudeUsage.xcodeproj \
  -scheme ClaudeUsageiOS \
  -configuration Debug \
  -destination 'generic/platform=iOS' \
  -allowProvisioningUpdates build
```

Then install the built app with `xcrun devicectl device install app --device
<IPHONE_UDID> <path-to/AI Usage.app>`.

### 5. Install The Watch App

The normal path is:

1. Build/run **ClaudeUsageiOS** to the iPhone.
2. Open the **Watch** app on iPhone.
3. Find **AI Usage** under **Available Apps**.
4. Tap **Install**.

For development builds, direct install is often more reliable:

```bash
xcrun devicectl list devices
```

Copy your watch identifier into `WATCH_UDID` in [`push-watch.sh`](push-watch.sh),
then run:

```bash
./push-watch.sh
```

Keep the watch awake and near the Mac. If the tunnel times out, leave it on the
charger and run the script again.

### 6. Add Widgets And Complications

- **iPhone widget**: long-press the Home Screen → **Edit** → **Add Widget** →
  search **AI Usage** → choose Small, Medium, or Large.
- **Watch app**: open **AI Usage** on the watch and swipe between Claude and
  Codex pages.
- **Watch complications**: edit a watch face and choose **AI Usage**.
  `Claude session` and `Codex 5h` render as circular gauges in circular/corner
  slots; `Claude + Codex` is the rectangular two-provider view.

> **Can I sideload the iPhone/Watch app like the Mac DMG?** No. iOS/watchOS
> have no Developer-ID-equivalent. Others can either **build from source** (with
> their own Apple ID; installs only to their own registered devices) or you can
> distribute via **TestFlight / the App Store**. Only the macOS app ships as a
> runnable signed binary (the DMG).

## How it works

### Sign-in flow

- **Claude Code** → opens `https://claude.ai/login` inside a WKWebView,
  observes its `WKHTTPCookieStore`, and captures the `sessionKey` cookie the
  moment login succeeds. Stored in the Keychain (`ClaudeUsageWidget-Session`).
- **Codex** → reads `~/.codex/auth.json` directly. The bearer token written
  there by `codex login` is everything the API needs.

### Data flow

```
   Host app (unsandboxed)              Widget extension (sandboxed)
   ────────────────────────────        ────────────────────────────
   Refresher.tick() every 5 min  ──►   PlanCache.load()   ──► UI
     ├─ ClaudeAccountAPI                CodexCache.load()  ──► UI
     │    (sessionKey cookie)
     └─ CodexAccountAPI
          (bearer from auth.json)
                │
                ▼
        SharedContainer  ← single source of truth: writes JSON into
                          the widget's own sandbox container so the
                          widget can read it without App Groups.
```

On macOS, App Groups are *not* used — wildcard provisioning profiles strip the
entitlement, so the host writes directly to
`~/Library/Containers/com.marcovhv.claudeusage.widget/Data/Library/Application Support/`,
which the widget can read from its own sandbox.

### Cross-device sync (iPhone / Watch)

The same `tick()` also publishes a `UsageSnapshot` (summary + plan + codex +
statuses) to your **private CloudKit database** via `SnapshotSync`. The Mac is
the **sole writer** — it overwrites a single `latest` record each cycle, so
there are no merge conflicts. The iPhone and Watch fetch that record (with a
local cache fallback and a hard timeout so the UI never hangs). This *does*
require the iCloud capability, so those targets use real provisioning profiles,
unlike the macOS App-Group dodge above.

### Local fallback

If a network call fails, the widget falls back to scanning your local
`~/.claude/projects/**/*.jsonl` and `~/.codex/sessions/**/*.jsonl` for a
best-effort summary so the rings aren't blank.

## Privacy

- No analytics, telemetry, or third-party servers — usage requests go
  straight to `claude.ai` or `chatgpt.com` from your Mac.
- Cookies/tokens stay in the macOS Keychain.
- The iPhone/Watch sync uses **your own private CloudKit database** (Apple
  iCloud, tied to your Apple ID) — not a server I run. The snapshot is just the
  usage numbers; no credentials leave your Mac.
- Cached JSON usage data lives in each app's sandbox container; delete the
  app to delete the cache.

## Project layout

```
Sources/
  App/      ─ macOS host app (unsandboxed): refresh loop, login sheet,
              auth + API clients, preview UI. Publishes the CloudKit snapshot.
  Widget/   ─ macOS WidgetKit extension (sandboxed): TimelineProvider,
              reads cache from the shared on-disk location.
  iOS/      ─ iPhone app + Home Screen widget extension. Read-only; fetch the
              CloudKit snapshot. The watch app is embedded in the iPhone app.
  Watch/    ─ Apple Watch app + complications extension (watchOS). Read-only.
  Shared/   ─ Code compiled into every target: data models, JSONL scanner,
              widget views (Small/Medium/Large), UsageSnapshot, SnapshotSync
              (CloudKit), CloudUsageProvider, theme.
Resources/
  Assets.xcassets/  ─ App icon + logo image sets.
images/             ─ Source PNGs (clawd, openai, icon).
project.yml         ─ XcodeGen spec — single source of truth for the
                     Xcode project (macOS + iOS + watchOS targets).
release.sh          ─ Build + sign + (optional) notarize the macOS DMG.
push-watch.sh       ─ Install the watch app straight to a reachable Apple
                     Watch via devicectl (sidesteps the flaky Watch-app install).
```

## Roadmap / known limits

- Claude.ai login must complete in the embedded WKWebView. Google SSO
  occasionally trips reCAPTCHA inside web views; if that happens, the sheet
  still works — just complete the challenge.
- Widget extension is sandboxed (macOS requires it). Host app is
  unsandboxed because it scans `~/.claude` and `~/.codex` directly.
- All requests go straight to vendor APIs. No retries, no rate-limit
  backoff. If they 5xx, the widget keeps the last cache.

## Credits

Made by **Marco van Hylckama Vlieg**.

- Web — [ai-created.com](https://ai-created.com/)
- X — [@AIandDesign](https://x.com/AIandDesign)
- ☕ [Buy me a coffee](https://ko-fi.com/aianddesign)

Claude and Anthropic logos belong to Anthropic. OpenAI / Codex logos belong
to OpenAI. This is an independent third-party tool with no affiliation with
either company.

claude-usage

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

claude-usage

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README