Support

Gaugeline lives in the menu bar, at the top-right of your screen, and has no Dock icon. Before setup it shows a small gauge icon; once connected it shows your numbers, for example C 5h 42% 7d 81% </> 5h 93% 7d 41%. The amber C badge is Claude and the grey </> badge is Codex. Click it to open the menu. Settings… is at the bottom of the menu, or press ⌘, while the menu is open. If you have many menu bar items, it may be hidden behind the notch; quit a few other menu bar apps or use a menu bar manager.

macOS 15 or later, plus Claude Code signed in with a Claude Pro or Max plan and/or Codex signed in with a ChatGPT plan. Both tools only report usage limits for subscription plans. If you use an API key, there are no 5-hour or weekly limits to show.

Not on their own. Gaugeline gets your Claude limits from Claude Code, the command-line tool, which reports them after each reply. The Claude desktop and web apps don't share them with other apps. Your limits are shared across all of them, though, so usage in the desktop app or on claude.ai shows up in Gaugeline the next time Claude Code replies. Until then the numbers are dimmed as "Last updated by Claude Code …".

No. Gaugeline makes no network connections at all; it doesn't even have permission to. It only reads files that Claude Code and Codex save on your Mac, in folders you choose.

Settings › About › Welcome guide › Show Again…

Yes. Settings › General › Services has a switch for Claude and one for Codex: turning a service off hides it everywhere. Next to each are 5-hour and Weekly checkboxes that choose which limits appear in the menu bar; the dropdown always shows every limit.

Settings › General › Menu Bar sets the look. Style: All windows, Closest to the limit (one number per service: whichever limit is fullest) or Gauges. Numbers: Percent used or Percent remaining. The Preview row shows the result. Gaugeline follows your Mac's light or dark appearance automatically.

Claude Code can run a status line command after each reply, and it hands that command your current usage limits. Gaugeline adds a small command there that saves those numbers to a file Gaugeline can read.

1. Settings › Claude › Grant Access… (or Add to Claude Code… in the welcome window).
2. In the folder panel, select your .claude folder and click Grant Access.
3. A sheet shows exactly what will be added to ~/.claude/settings.json. Click Add to Claude Code, or Copy Instead to add it yourself, or Cancel. Nothing changes until you click Add to Claude Code.
4. Send any message in Claude Code. Your limits appear after the reply.

Prefer to do it by hand? Use Set up manually in Settings › Claude (or Set up manually instead in the welcome window) and paste the snippet it shows.

That's normal right after setup. Claude Code hands its usage numbers to the status line command after each reply, so Gaugeline has nothing to show until then.

1. Open Terminal and run claude (or use Claude Code in your editor).
2. Send any message and wait for the reply.
3. Click the Gaugeline menu: your 5-hour and weekly limits appear.

Still waiting? Check that:

• Settings › Claude shows a green check next to Add status line command, with "Added. Claude Code saves your limits after each reply."
• You're signed in to Claude Code with a Pro or Max subscription (run /status in Claude Code). API-key sessions don't include rate limits.
• Your Claude Code is up to date. Older versions don't pass rate limits to the status line.
• If you set CLAUDE_CONFIG_DIR to a custom folder, Gaugeline needs access to that folder: Settings › Claude › Revoke, then Grant Access… and pick it.
• Click Check Now in Settings › Claude › Status.

Claude Code and Codex only save new numbers when you use them. If you haven't, your usage hasn't changed either, so the numbers are still right; the menu just tells you how old they are once they're more than 30 minutes old. Usage on claude.ai, in the Claude desktop app or in ChatGPT Work counts against the same limits but only shows up after the next Claude Code or Codex update, so numbers more than a day old are dimmed as a hint to check. Send a message in Claude Code (or use Codex) and they're current again. Once a window's reset time passes, Gaugeline knows it has reset even without new data.

No. Gaugeline's command runs your existing command unchanged, so your status line keeps showing exactly as before. Your command sits verbatim between two marker lines, # gaugeline-v1-begin and # gaugeline-v1-end. Remove from Claude Code puts your original command back exactly.

Someone (maybe you) edited Gaugeline's command in settings.json, so Gaugeline won't touch it. Either fix it by hand using the snippet under Set up manually, or remove it by hand (see below) and add it again.

Click Update… in Settings › Claude. You'll see the new command before anything changes, then click Update in Claude Code.

Gaugeline never rewrites a settings.json it can't parse. Open ~/.claude/settings.json in a text editor, fix the JSON error (often a trailing comma), and try again. Or use Set up manually. The same applies to "settings.json is a link Gaugeline can't follow".

macOS no longer lets Gaugeline open the folder (for example after you moved it). Click Grant Access… and choose the folder again.

• settings.json: read, and changed only when you click Add to Claude Code or Remove from Claude Code. Only the "statusLine" entry is edited; the rest of the file, including its formatting, stays exactly as it was.
• settings.json.gaugeline-backup: a copy of your settings.json from before Gaugeline's first change. It's created once and never overwritten.
• gaugeline-rate-limits.json: the usage numbers Claude Code saves through the command, readable only by your user account.

Gaugeline doesn't read your conversations, projects or credentials.

Settings › Claude › Remove from Claude Code. This removes Gaugeline's command from settings.json, or puts back your own status line exactly if you had one, and deletes gaugeline-rate-limits.json. Do this before deleting the app.

If you click Revoke while the command is still added, Gaugeline asks "Remove from Claude Code first?". Choose Remove & Revoke.

If the command stays after the app is gone, it's harmless: Claude Code keeps running it, it keeps saving that one small file, and your own status line (if any) keeps working. To remove it anyway:

1. Open ~/.claude/settings.json in a text editor and find the "statusLine" entry. If its "command" starts with # Gaugeline status line bridge, it's Gaugeline's.
2. If nothing sits between # gaugeline-v1-begin\n and # gaugeline-v1-end, you had no status line before: delete the whole "statusLine": { … } entry (and the comma before or after it).
3. Otherwise, your original command is the text between # gaugeline-v1-begin\n and \n# gaugeline-v1-end. Make that text the whole value of "command".
4. Save the file.

Or restore the backup. It is your settings.json from before Gaugeline first changed it, so check that it doesn't undo other changes you've made since:

diff ~/.claude/settings.json.gaugeline-backup ~/.claude/settings.json
cp ~/.claude/settings.json.gaugeline-backup ~/.claude/settings.json

Then delete the leftovers:

rm -f ~/.claude/gaugeline-rate-limits.json ~/.claude/gaugeline-rate-limits.json.* ~/.claude/settings.json.gaugeline-backup

If you use CLAUDE_CONFIG_DIR, the same files are in that folder instead of ~/.claude. Gaugeline's own settings live in ~/Library/Containers/com.victorshammas.gaugeline, which you can delete too.

Settings › Codex › Grant Access… (or Grant Access to .codex… in the welcome window). The folder panel opens at your .codex folder; just click Grant Access. If it doesn't, press ⌘⇧G, type ~/.codex and press Return. Gaugeline only reads this folder, and only Codex's session logs in it. It never opens Codex's sign-in file.

Codex records your limits in its session logs while you use it. Run a Codex session with any prompt, then click Check Now in Settings › Codex. Make sure you're signed in to Codex with your ChatGPT account, not an API key. If you set CODEX_HOME, use Choose Another Folder… to pick that folder.

Settings › Codex › Revoke Access. To hide Codex without revoking, turn off Codex in Settings › General › Services (or Show Codex usage in Settings › Codex).

Gaugeline shows the latest numbers your tools saved, and they only save them while you use them. Small differences are normal; they catch up after your next message. Refresh Now (⌘R) in the menu re-reads the files right away.

Gaugeline compares how much of the limit you've used with how much of the window has passed. If you keep going at your current rate, you'll hit the limit about that long before it resets. The thin marker on each bar shows "even pace": where you'd be if you spread usage evenly.

Settings › General › Notifications: turn on Alert me when a limit runs high and set Alert at. Also tell me when a limit resets is optional. Click Send Test Notification to check. If you see "Notifications are turned off for Gaugeline", click Open Notification Settings… and allow them. Alerts fire once per window when fresh numbers cross your level.

Settings › General › Open Gaugeline at login. It's off until you turn it on. If you see "Waiting for approval in System Settings", click Open Login Items… and allow Gaugeline.

Yes. In the welcome window, click Just looking? Explore with demo data, or go to Settings › About › Show demo data. The menu fills with sample numbers, marked "Demo data", so you can try bars, countdowns, pace forecasts and alerts. Click Turn Off in the menu, or turn off Show demo data, to see your real usage.