AI usage widget

An iPhone home-screen widget that tracks your Claude (Pro/Max subscription) and Codex (ChatGPT plan) usage limits — session/weekly percentages, reset times in your local timezone, extra-usage spend, Codex usage-limit resets, and a reminder when free credits are available.

_{Home Screen — medium widget}

_{Lock Screen — rectangular widget}

┌─────────────┐   every 5 min   ┌────────────┐   fetch    ┌──────────────────┐
│ PC collector │ ──────────────▶ │ secret gist │ ◀──────── │ iPhone widget     │
│ (Node.js)    │  usage.json     │ (GitHub)    │           │ (Scriptable app)  │
└─────────────┘                 └────────────┘           └──────────────────┘

There are two ways to set it up:

	What you get	What you need
Path A — PC + phone	Claude + Codex, credits reminder	A computer that's on regularly, Node.js, GitHub account, iPhone
Path B — phone only	Claude only	Just an iPhone with the free Scriptable app

Codex can't do phone-only: its sign-in flow requires a local callback server on a computer. Claude's OAuth flow has a manual-code variant that works entirely on the phone.

Disclaimer: this is an unofficial project, not affiliated with or endorsed by Anthropic or OpenAI. The usage endpoints used here are the same ones the official apps/CLIs use, but they are not publicly documented. A future change on Anthropic's or OpenAI's side may require updating this project.

Security: your login tokens never leave your own devices. The gist contains only percentages and reset timestamps — no tokens, no content, no account ids. Keep the gist secret (unlisted) anyway.

---

Path A — full setup (PC + phone)

On the PC

1. Install Node.js, the GitHub CLI, and clone this repo.

2. Claude login — install Claude Code and run:

   claude

   Complete /login with your Claude subscription account. ⚠️ claude setup-token does NOT work for this — its token lacks the user:profile scope the usage endpoint requires. Use the normal login.

3. Codex login — install the Codex CLI and run codex, signing in with your ChatGPT account. (Skip if you only want Claude.)

4. GitHub gist — authenticate and create your secret gist:

   gh auth login

   node collector.js

   gh gist create usage.json -d "AI usage widget data"

   Note the gist id from the printed URL (the hex string after your username).

5. Configure — create config.local.json next to collector.js:

   { "gist_id": "PASTE_YOUR_GIST_ID" }

   Run node collector.js again — it should end with Gist publish: ok.

6. Schedule it — Windows (every 5 minutes, no visible window):

   schtasks /Create /TN "AI Usage Collector" /TR "wscript.exe \"%CD%\run-collector.vbs\"" /SC MINUTE /MO 5 /F

   macOS/Linux — add to crontab -e:

   */5 * * * * /usr/local/bin/node /path/to/collector.js
   

On the iPhone

7. Install Scriptable (free, App Store).
8. Add three scripts (+ button, paste, name them): scriptable-widget.js as AI Usage, scriptable-alert.js as AI Usage Alert, scriptable-setup.js as AI Usage Setup.
9. Run AI Usage Setup once and paste your gist's raw URL: https://gist.githubusercontent.com/<your-username>/<gist-id>/raw/usage.json
10. Long-press the home screen → add a Scriptable widget (medium) → set Script to AI Usage.
11. Optional notifications: Shortcuts app → Automation → New → Time of Day (daily) → Run Immediately → action "Run Script" (Scriptable) → AI Usage Alert. It notifies when credits appear or a limit passes 85%.

Path B — phone only (Claude only)

1. Install Scriptable (free, App Store).
2. Add three scripts: scriptable-claude-login.js as Claude Login, scriptable-widget.js as AI Usage, scriptable-alert.js as AI Usage Alert.
3. Run Claude Login: Safari opens claude.ai → log in with your Claude subscription → approve → copy the code shown → return to Scriptable → paste. Tokens are stored in your device Keychain only.
4. Add the widget as in Path A step 10 (the Codex column will show "needs PC setup").
5. Optional notifications as in Path A step 11.

Lock Screen widget (optional)

The same AI Usage script also renders as a Lock Screen widget (iOS 16+): long-press the Lock Screen → Customize → Lock Screen → tap the widget area under the clock → add Scriptable (rectangular) → tap it → choose AI Usage.

As in the screenshot above, the rectangular version is a clean three-row readout — no bars, since iOS renders Lock Screen widgets tinted monochrome at roughly 160×72pt. A ⚠ appears next to the first row if the data has gone stale (PC collector asleep). There's also an inline variant for the text slot above the clock, showing AI C 11%·16% X 3%.

Note that iOS fits two rectangular widgets side by side in that strip — there's no full-width option — so the layout is built for half-width. Extra-usage spend and Codex reset counts live on the Home Screen widget, which is unchanged.

Multiple users

Each person must authenticate with their own accounts on their own devices — don't share gists or tokens, and don't run a collector on someone else's behalf (that would mean holding their account credentials).

• No PC available → Path B (about five minutes, Claude only).
• PC available → Path A for both services.

The repo itself contains no personal data by design — everything account-specific lives in gitignored local files and the device Keychain.

Files

File	Runs on	Purpose
collector.js	PC	Fetches Claude + Codex usage, writes usage.json, publishes to your gist
run-collector.vbs	PC (Windows)	Runs the collector without flashing a console window
scriptable-widget.js	iPhone	The home-screen widget
scriptable-alert.js	iPhone	Daily notification for credits / near-limit
scriptable-setup.js	iPhone	One-time: store your gist URL (Path A)
scriptable-claude-login.js	iPhone	One-time: phone-only Claude login (Path B)

License

MIT — see LICENSE.