Using AI Usage Tracker

Install

1. Download the disk image and open it.
2. Drag AI Usage Tracker onto the Applications folder.
3. Open AI Usage Tracker from Applications. It lives in the menu bar at the top of the screen, not in the Dock.

It needs macOS 14 or later. Only one copy runs at a time; opening a second one just quits it.

Download for Mac

First-time setup

The first time you open AI Usage Tracker, a short setup window walks you through four steps. You can go back at any point with Back.

1. Welcome

A summary of what the app does. Click Get Started.

2. Sign in

Click Sign In… next to Claude, ChatGPT or both. Your browser opens on Claude's or ChatGPT's own sign-in page. Sign in to your account there; the browser tab then says You're signed in to AI Usage Tracker and you can close it.

You never copy cookies or tokens, and AI Usage Tracker never reads or changes the logins of Claude Code or the Codex CLI. Your sign-in is stored in your Mac's keychain.

• Signed-in accounts get a green check. To track a second account for the same service, click Add Another….
• If the browser didn't open, click Cancel and try again. A sign-in that isn't finished within 5 minutes times out.
• No account yet? Skip for Now takes you to the end; you can sign in later from the menu bar.

3. Choose what shows

Turn on the limits you want in the menu bar. Only limits your plan actually has are listed. Everything appears in the popover either way, so this is only about what you see at a glance. You can change it any time; see Choosing what shows.

4. Finish

Turn on Open AI Usage Tracker when you log in if you want it running all the time, then click Done. If macOS asks, allow it under System Settings → General → Login Items.

Reading the menu bar

Each value is how much of that limit you've used. A short label says which limit it is: 5h for the 5-hour window, Wk for the weekly limit, the model name (such as Opus) for a model's own weekly limit, and Extra for Claude extra usage. A Claude or ChatGPT mark in front groups each service's values.

Colors

The time marker

The thin tick on bars and rings shows where you'd be by now if you used the limit evenly across its window. Its color tells you your pace:

• Green: you're using less than an even pace. You have room to spare.
• Blue: you're about on pace.
• Red: you're ahead of pace and will run out before the window resets.

A dimmed value is out of date, usually because the last refresh failed. A dash means there's no value yet.

The popover

Click the menu bar item to open the popover. It shows every limit on an account, whether or not it's in the menu bar, as a card each.

With more than one account, buttons along the top switch between them. It opens on the first account in Settings → Accounts; Move Up and Move Down in an account's ⋯ menu change which comes first. A dot on a button means that account needs attention, such as signing in again.

• Each account shows its plan, such as Max 5x or Plus.
• Each card shows how much of the limit you've used, how much is left, a bar with the time marker, and how long until it resets.
• Under that is your pace: Under pace, On pace, or, in red, Ahead of pace. At 100% it says Limit reached. Hold the pointer over the pace or the reset time for the details, such as about 67% at reset, runs out in 1h 20m or the exact reset time.
• Prefer one compact line per limit? Choose List under Settings → General → Popover.
• Claude extra usage shows money: $12.40 of $50.00, or Off when extra usage is turned off for your account.
• The footer shows whether Claude and OpenAI report any service problems (click to open their status pages) and when usage was last updated.

Buttons along the top

• Refresh (or ⌘R) fetches fresh numbers now.
• Pin turns the popover into a small window that stays open, floats above other windows and follows you to every desktop, including full-screen apps. You can also drag the popover away to do the same. Close the window to put it back.
• ⋯ opens the same menu as right-clicking the menu bar item.

The popover closes when you click in another app.

Messages you might see

• Your sign-in has expired, with a Sign In Again… button. Click it and sign in in your browser.
• Couldn't refresh, with the reason and when it will retry. Usually a network problem; it sorts itself out.
• Showing data from 12m ago. The numbers are older than they should be.
• Refreshing is paused for this account. You paused it in Settings → Accounts.

The right-click menu

Right-click (or Control-click) the menu bar item for the app's menu. AI Usage Tracker has no Dock icon, so this is where everything else lives:

• Sign In Again to… appears at the top when an account needs it.
• Menu Bar: change what shows without opening Settings (see the next section).
• Refresh Now, Refresh Every (1 to 30 minutes) and Reset Times (system setting, 12-hour or 24-hour).
• Sign In with Claude… and Sign In with ChatGPT… to add accounts.
• Sign Out: signs out of an account right away, without asking. Settings → Accounts asks first.
• History…, About AI Usage Tracker, Check for Updates…, Settings… and Quit AI Usage Tracker.

Choosing what shows

The menu bar can show any mix of limits from any of your accounts, as one item or several. Change it in Settings → Menu Bar, or from the right-click menu under Menu Bar.

Menu bar items

Each item is one spot in the menu bar and can hold several limits. For each item you choose:

• Style: Percentage, Bar and Percentage, Battery, Logo and Bars, Compact Numbers, Concentric Rings or Dots.
• Label: Automatic (5h, Wk, Opus…), None, or your own text. Under Value labels you can rename or hide the label of each limit separately.
• Show time until reset adds something like 2h 14m after each value.
• Limits shown: which limits the item holds. A limit can only be in one item at a time.

Use Add Menu Bar Item for a new item, Split into Separate Items to give each limit its own item, Combine All into One Item to merge them, and Remove to take an item away. To reorder items in the menu bar, hold ⌘ and drag them.

In the right-click menu, Menu Bar lists every limit with a checkmark. Ticking one adds it to the first item.

Appearance

• Colors: By usage level (the green-to-red scale above), Monochrome, or One color of your choice.
• Show: Percent used or Percent remaining. This only changes the menu bar; colors and the popover always go by how much you've used.
• Show time marker, Color the marker by pace and Show provider icons turn those details on or off.

Accounts

You can sign in to several Claude and ChatGPT accounts, for example work and personal. Manage them in Settings → Accounts.

• Nickname: type a name to show instead of the email address, or click the dice for a suggestion.
• The ⋯ menu on each account has Pause Refreshing (its last numbers stay on screen), Move Up and Move Down (the order here is the order in the popover and menus), and Sign Out….
• Signing out removes that account's sign-in from your keychain, takes its limits out of the menu bar and deletes its history.
• Signing in to the same account again just renews it; it doesn't create a duplicate.

Notifications

• By default you're notified when any limit passes 75%, 90% and 95%. Remove a threshold with its ✕, or type a number from 1 to 100 and click Add.
• Each threshold notifies once per window. If usage jumps past several at once, you get one notification for the highest.
• Notify when a sign-in needs renewing is on by default. Notify when a limit resets after passing a threshold is off.
• Pick a Sound, and use Send Test Notification to check everything works.
• Clicking a notification opens the popover.

If notifications are turned off for AI Usage Tracker in macOS, the pane says so and offers Open System Settings.

History

AI Usage Tracker keeps a record of each limit so you can see how your week went. Open it with History… in the right-click menu, or Settings → History.

• Pick a Limit and a Range (24 hours, 7 days, 30 days or 90 days) to see a chart, with your notification thresholds drawn as dashed lines.
• Windows lists recent windows with their peak usage, so you can see which weeks came close to the limit.
• Export… saves one limit or everything as CSV or JSON.

History builds up as usage refreshes, so it starts empty. It stays on your Mac for 90 days and holds only percentages and reset times.

Claude Code

If you use Claude Code, Settings → Claude Code has three optional extras.

Status line

Click Install to show your limits under Claude Code's prompt, like the Preview row. The line refreshes every 10 seconds. It only reads a small file AI Usage Tracker keeps up to date, so no sign-ins end up in the script, and your Claude Code settings.json is backed up before each change.

• Options add the model name, the effort level and the time until reset, and color values by usage level.
• Limits can follow the menu bar or use its own choice.
• If Claude Code already had a status line, Replace swaps it out and Uninstall later puts the old one back.

Terminal launchers

Useful when you have more than one Claude account. Add Launcher creates a command (such as claude-cosmic-otter) in ~/.local/bin that runs Claude Code with that account's own settings folder. The first time you run it, Claude Code asks you to sign in in that folder. AI Usage Tracker never touches those logins.

The claude-auto command runs whichever account you pick under claude-auto runs. With two or more launchers, Switch automatically at 100% moves claude-auto to the account with the most room left when one hits its limit, and tells you.

Auto-start session

Claude's 5-hour window starts with your first message. Start a 5-hour window at set times starts it for you, say at 7:00 on weekdays, so it resets earlier in your day. At each time, if the window isn't already running, AI Usage Tracker runs your own claude command once with a one-line prompt on the smallest model. That uses a little of your quota. Start Now runs it immediately.

It's off unless you turn it on, and it does nothing on plans that have no 5-hour window.

Keyboard shortcuts

In Settings → Shortcuts you can set system-wide shortcuts to open or close the popover and to refresh now. Neither is set until you choose one: click Record Shortcut and press the keys. Shortcuts need ⌘, ⌃ or ⌥, or a function key. Esc cancels and Delete clears.

In the popover, ⌘R refreshes.

General settings

• Open at login starts AI Usage Tracker when you log in.
• Refresh every sets how often usage is fetched: 1, 2, 5 (the default), 10, 15 or 30 minutes. It also refreshes after your Mac wakes, when the network comes back, and when you click Refresh.
• Popover switches the popover between Cards (the default) and a compact List.
• Clock chooses 12-hour or 24-hour reset times, or follows your Mac.

Updates

AI Usage Tracker checks for updates once a day. When one is ready you get a notification, and the right-click menu item changes to Install Update…. Nothing pops up over your work. Click it to see what's new and install; the app restarts on the new version.

To check now, or to turn automatic checks off, open Settings → About.

Troubleshooting

ChatGPT sign-in says a port is in use

ChatGPT sign-in needs local port 1455 or 1457. Those are also used by codex login. If one is waiting in a terminal, finish or cancel it, then try again.

Sign-in timed out or failed

Start it again from the right-click menu or Settings → Accounts. If your browser didn't open, check that you have a default browser set.

"Your sign-in has expired"

Click Sign In Again… in the popover or the right-click menu. Your settings and history are kept.

macOS asks to use the keychain

After some updates, macOS may ask once whether AI Usage Tracker can use its saved sign-ins. Choose Always Allow.

No notifications appear

Check System Settings → Notifications → AI Usage Tracker. While your screen is shared or mirrored, macOS hides notification banners, but they still arrive in Notification Center.

A value is dimmed or missing

The last refresh didn't work. Open the popover to see why, or click Refresh. Failed refreshes retry on their own, waiting a little longer each time, up to 15 minutes.

Your data and uninstalling

AI Usage Tracker talks only to Claude, ChatGPT and their status pages. There are no analytics.

• Sign-ins are in your login keychain, under com.letyournerdbeheard.ai-usage-tracker.credentials.
• Settings and history are in ~/Library/Application Support/AI Usage Tracker. Settings → About → Show in Finder opens it.

To uninstall

1. If you installed the Claude Code status line or terminal launchers, remove them first in Settings → Claude Code. That puts your previous status line back.
2. Sign out of each account in Settings → Accounts, which removes its sign-in from your keychain.
3. Quit AI Usage Tracker from its right-click menu and move it from Applications to the Trash.
4. Delete the ~/Library/Application Support/AI Usage Tracker folder.