User manual · version 2.4
Know before you hit the limit.
A practical guide to setup, Claude Code, Codex, Gemini, forecasts, Stats, iPhone, iPad, widgets, Apple Watch, and troubleshooting.
Step 01 · Install
One download covers every device
Get AI Session Meter on the App Store. A single listing installs the Mac menu bar app, the iPhone/iPad app, and the Apple Watch app — one purchase later unlocks all of them.
- Mac — macOS 13 (Ventura) or later
- iPhone / iPad — iOS 16 or later
- Claude Max or Pro subscription — required to read the usage endpoint; free or API-only Claude accounts can't be metered
Step 02 · Trial
Your 14-day trial starts by itself
On first launch every feature is unlocked for 14 days. There is nothing to activate — the welcome screen simply tells you the trial has begun. Use the whole app: forecasts, Stats, Codex, sync, widgets, Watch.
When the trial ends, the app keeps running and shows an unlock screen instead of the meters. A one-time $4.99 purchase brings everything back permanently — no subscription (see Step 10).
Bought the app before it went free? Your full access is restored automatically — no purchase needed.
Step 03 · Connect
Connect your Claude account on the Mac
The first time you launch AI Session Meter, a setup guide opens automatically and walks you through connecting your Claude account in a couple of clicks. Click Sign in, complete Claude's sign-in in your browser, and the guide shows Claude connected once your session is live. Reopen it anytime from Setup guide… in the popover.
Connection expired? The account switches to needs reconnect — click Sign in again to restore it in a couple of clicks.
Manual setup from the Terminal
- Run
claudeonce in Terminal so a fresh session token exists. - Copy the token to your clipboard:
security find-generic-password -s "Claude Code-credentials" -w | pbcopy- Click the AI Session Meter icon in the menu bar, paste into the token field, and press Save.
- The popover shows “Authenticated (auto-refresh)” — from now on the app refreshes the token for you. You normally never paste it again.
security is Apple's signed, built-in tool. If a Keychain prompt appears, click Allow — AI Session Meter itself never touches the Keychain.
More than one account
Use Add account in the popover to track several subscriptions side by side. Each account can be renamed to a friendly alias, hidden, re-ordered, or removed — removing an account deletes its stored token from your Mac.
Optional: API spend
Paste a Claude Admin key (sk-ant-admin…) instead of a session token to track this month's API spend alongside your subscriptions.
Step 04 · Menu bar
Read the menu bar at a glance
The menu bar icon shows each account's current session percentage (for example 5% · 59%), tinted by its forecast. If any account is on pace to hit its limit before the window resets, the icon flips to a warning.
Click the icon to open the popover:
- Session row — utilization of the current 5-hour window, time until it resets — now shown with the clock time alongside it, for example
Resets in 3h 12m (14:54)— and a forecast caption such as “On pace to hit the limit at 16:40” or “Safe · ~42% by reset”. - Weekly rows — the weekly limits (all models and per-model), each with its reset spelled out:
Resets in 5d 22h (Wed 14:00). - Codex rows — Codex rate limits, if you've enabled Codex tracking (Step 06).
- Stats & Settings — buttons to the Stats window and app settings.
Every reset row in the popover now shares this same format, and once a reset has gone by it simply reads “Reset passed.”
Everything refreshes automatically at a polite rate — there's no need to press refresh repeatedly.
Step 05 · Forecasts
What the forecast badges mean
AI Session Meter measures your real recent pace instead of assuming every session behaves the same. Flat usage stays at the current percentage; increasing usage shows where you may land by reset — and a projection never drops below what you have already used.
On the Daily and Weekly charts, that forecast now extends onto the graph itself: an amber band marks the range you're likely to land in by the next reset, bounded by dashed upper and lower lines. The chart's timeline stretches out to the next reset, marked with its own dashed line and clock time.
At the current pace you'll stay under the limit through the reset.
You may land near the limit — worth keeping an eye on.
On pace to reach the limit before the window resets, with the estimated time.
Not enough evidence yet — the app says so instead of claiming false precision.
Just reset? A short Learning period is normal. The app deliberately discards the previous window's pace and waits for fresh readings from the new window. A first low-confidence range appears after enough same-window evidence arrives, then tightens as more readings are collected.
Hover a reset marker on any Daily or Weekly chart — or touch it on iPhone / iPad — to see which account resets there, and whether it's the 5-hour session reset or the weekly reset.
Step 06 · Providers
Connect Claude Code, Codex, and Gemini
Each provider exposes different data. AI Session Meter keeps those meanings separate instead of pretending that every chart is a token counter.
Claude Code
Live session and weekly utilization, reset times, forecasts, account/model rows, and locally observed activity. Claude Max or Pro is required for the usage endpoint.
Codex
Current rate limits can be read from a connected ChatGPT workspace. Detailed model/token history comes from Codex CLI activity on the Mac. The iPhone can fetch current limits directly; longer token history syncs from the Mac.
Gemini
Five-hour and weekly quota utilization from the official Antigravity CLI, with history, activity, reset markers, and forecasts. Gemini charts are quota percentages—not token counts.
Set visibility and sources
Open Settings on the Mac to show or hide providers, choose a Codex sessions folder, control menu-bar rows, notifications, warning thresholds, sync, and launch-at-login behavior. A source label such as Live, Local activity, or Last known tells you how fresh a reading is.
Sampling labels are literal. Claude/Codex token charts may show Tokens per 10 min. Gemini shows quota utilization and says 10 min samples or 1 hour samples according to the observations actually stored.
Step 07 · Stats
Explore the Stats window
Open Stats from the popover. The provider switch at the top moves between Claude Code, Codex, and Gemini; Stats remembers your last view and range.
- Daily — recent session utilization, reset markers, and a projection to the next reset.
- Weekly — this week's utilization per provider, account, and model. Choose 12 hours, 24 hours, 3 days, 7 days, or 14 days.
- Overview — an activity heatmap plus totals such as tokens, sessions, active days, streaks, and favorite model.
- Models — model-by-model history over 12 hours, 24 hours, the last 7 days, the last 30 days, or all time where the source supports it.
Two chart meanings: Claude/Codex model charts show tokens used inside each time bucket, so a line may go down without a reset. Gemini charts show quota utilization instead. Read the chart title and sampling label before comparing providers.
Merging an account's history
If the same account shows up under an old name (for example after deleting and re-adding it), use the link button in the Stats toolbar to merge the historical identity into the current one. Merging never rewrites history — it only groups it — and can be undone with Separate.
Step 08 · iPhone & iPad
Take it with you
There are three complementary ways to get data on iPhone or iPad — use the connections you need:
- Sign in on the device. In the app's Settings, connect your Claude account to fetch live session and weekly usage right on the phone — no Mac required.
- Connect ChatGPT on the device. A connected workspace can fetch current Codex limits directly.
- Sync from your Mac. Sign in to the same iCloud account on both devices and keep the Mac app running. Longer history, Mac-observed Codex token activity, Gemini data, and forecasts appear automatically.
The phone cannot read CLI files on your Mac, so Mac-origin history needs iCloud sync. Check the Updated and Checked timestamps before comparing devices. Until real data arrives, a clearly labeled sample-data banner lets you explore the screens and disappears when live data is available.
Need a closer look? Pinch outward anywhere on the main app screen to zoom continuously up to 3×. The enlarged scale stays in place after you lift your fingers, so you can read and use the screen; pinch inward to return to the normal 1× size. Scrolling, charts, pull to refresh, tabs, and buttons continue to work with the pinch gesture.
iPhone
iPad
Step 09 · Widgets & Watch
Widgets and Apple Watch
Home Screen widgets
- Touch and hold the Home Screen, then tap the Edit / ＋ button.
- Search for AI Session Meter.
- Choose a Daily or Weekly widget in the size you like.
The app's Widgets tab previews every layout before you commit.
Apple Watch
The Watch app shows your current session and weekly limits at a glance, and a watch-face complication keeps the number one raise-of-the-wrist away. The Watch displays history recorded by your iPhone and Mac — it never connects to an AI service itself.
Step 10 · Unlock
Unlock everything, once
After the 14-day trial, a single $4.99 purchase — Unlock Everything — restores every feature permanently on all your devices. It's a one-time purchase, not a subscription.
- Where: the unlock screen that appears after the trial, or Settings on Mac and iPhone at any time.
- Restore Purchases — reinstalling, or setting up a new device? Tap Restore and your purchase comes back through your Apple account.
- Previous paid-era customers — if you bought the app before it went free, full access is restored automatically.
Reference · Troubleshooting
When something looks wrong
“Token expired” or an auth error
Run claude once to mint a fresh session, copy the token again with the command in Step 03, and paste it via Update token in the popover.
It says I need a Claude Max / Pro subscription
The usage endpoint only exists for Max and Pro subscriptions. Free or API-only accounts can't be metered.
HTTP 429 errors
The usage endpoint throttles aggressive polling. The app waits out the server's Retry-After (plus a safety margin) and recovers on its own.
The iPhone app shows no data
Connect Claude or ChatGPT in Settings, then check the source timestamps. For Mac-origin history and Gemini data, confirm both devices use the same iCloud account and the Mac app has recently run.
A forecast is missing just after a reset
This is intentional. The old window's pace is not reused for the new one. The app shows Learning until it has enough fresh observations, then draws a provisional range and refines it automatically.
A “Tokens per 10 min” line goes down without a reset
That graph is not cumulative. Each point is the number of tokens observed in that time bucket, so a quieter bucket is lower than the previous one.
Gemini says “1 hour samples” instead of “10 min samples”
The label follows the density of the stored observations. When only hourly observations are available, the app avoids implying 10-minute precision.
I still use an old DMG install
Public DMG distribution has been discontinued. Existing installs keep working but no longer receive updates — install from the Mac App Store to stay current.
A note on reliability: the app reads provider usage endpoints and local CLI files. A provider-side change at Anthropic, OpenAI, or Google can interrupt metering until an app update ships.
Still stuck? Email [email protected] — or see the Support page.
Reference · Privacy
Private by design
- The app never calls an AI model and never consumes your usage quota.
- Provider credentials stay on your devices and are sent only to the corresponding provider when requesting usage data.
- No analytics, no tracking, no ads. Sync uses only your own iCloud account.
Full policy: Privacy Policy.
