Copilot Usage Bar

Your GitHub Copilot credits in the macOS menu bar, like a battery — so you notice you're running low before you actually are.

menu bar:   10%          <- credits LEFT this cycle

dropdown:
  AI credits this cycle
  44.812 / 50.000                    10% left
  ########################----------
  2 days left - resets 1 Aug 2026
  Projected 49.001 by reset - 2% left

Install

1. Download the latest CopilotUsage-*.dmg from Releases.

2. Open it and drag the app onto Applications.

3. macOS will refuse to open it the first time — it isn't notarised by Apple, because it's an internal tool rather than an App Store download. Clear the download flag:

   xattr -dr com.apple.quarantine /Applications/CopilotUsageBar.app
   

   Prefer not to use Terminal? Open it once, let it be blocked, then go to System Settings → Privacy & Security and click Open Anyway.

4. Look for the Copilot mark in your menu bar. No Dock icon, no window.

Not seeing it? The menu bar hides items when it runs out of room — sooner than you'd expect on a Mac with a notch. Quit another menu bar app, or check Bartender / Ice / Hidden Bar.

First run

There's nothing to set up by hand. The app reads your usage through the GitHub CLI, so it shows your numbers with no tokens to paste. If anything is missing, the dropdown becomes a short checklist and does the work for you:

• Install GitHub CLI — uses Homebrew if you already have it. If you don't, it downloads GitHub's official CLI build into the app's own folder. No Homebrew, no admin password, nothing system-wide. The download is checked against GitHub's code signature before it's ever run.
• Sign in to GitHub — shows a one-time code and opens github.com/login/device in your browser. Type the code there and the app picks it up on its own.

Nothing is downloaded or installed until you click. If your sign-in later expires, the dropdown says so and offers the same one-click flow.

Using it

Refresh now	Force an update. It polls every 5 minutes and on wake from sleep.
Showing: credits left	Click to count up what you've used instead of down what's left. The menu bar, headline and forecast all follow.
Low-credit warnings	Notifications at 25% and 10% left (= 75% / 90% used), plus one when the forecast says you're on track to run out. Each fires once per cycle.
Track usage history	Records every successful refresh to a local history store. On by default; turning it off stops new recordings but never deletes what's already there.
Launch at login	Starts automatically when you log in.
Usage history…	Opens the History window — charts, a table, and export/import/sync for everything recorded. See below.

The forecast projects your current spending rate to the end of the cycle and turns orange when you're heading past your limit.

Numbers follow your Mac's language and region settings.

Usage history

Usage history… opens a separate window with four ways to look at your usage over time, picked with a Day / Week / Cycle / Year range selector (Cycle is the default):

• Credits per day/hour/month — a bar chart, bucketed to match the selected range.
• Cycle burn-down — how the current cycle's credits have drained so far. Shown only for Cycle.
• Stat tiles — headline numbers for the selected range.
• Usage by hour and weekday — a heatmap of when credits get spent. Shown for Cycle and Year.

Toggle Show as table for the same data as rows instead of charts.

Export… writes every recorded reading to an NDJSON file — one SampleRecord as JSON per line — the same format used by iCloud sync (see below). Import… reads one back in and merges it with what's already stored. Delete All History… removes every reading on this Mac; it cannot be undone.

Recording is controlled by the Track usage history toggle in the main dropdown (see the table above) — on by default.

Sync via iCloud Drive, in the History window, is off by default. Turning it on writes this Mac's readings to its own file in ~/Library/Mobile Documents/com~apple~CloudDocs/CopilotUsageBar/ and reads back any other Mac's file from the same folder — plain files that iCloud Drive syncs on its own, not CloudKit, so no iCloud entitlement is involved. Show in Finder opens that folder directly.

Requirements

• macOS 14 or later (universal — Apple Silicon and Intel)
• A Copilot plan with credits (Business / Enterprise)

Privacy

The app stores no credentials. It asks the gh CLI for a token on each refresh, holds it in memory for one request, and writes nothing to disk or the Keychain. It talks only to api.github.com and github.com.

Usage history is stored locally by default, in ~/Library/Application Support/CopilotUsageBar/History/. iCloud sync is opt-in and off by default; turning it on writes only to your own iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/CopilotUsageBar/) — no entitlement, no third-party server, iCloud Drive syncs the plain files itself. None of this changes what's said above: the app still stores no GitHub token.

To remove the CLI copy the app installed for you: delete ~/Library/Application Support/CopilotUsageBar/bin/.

Building from source

./build.sh              # universal build → CopilotUsageBar.app
./build.sh --install    # also copy to /Applications and relaunch
./make-dmg.sh           # package the built app into a .dmg

./make-icon.sh regenerates the app icon from Resources/AppIcon.svg and needs Inkscape — you only need it if you change the icon; the generated files are committed.

Signing is automatic: a Developer ID Application certificate is used if one is present (and the DMG is notarised if NOTARY_PROFILE is configured), otherwise the build is ad-hoc signed for local use.

Useful when something looks wrong:

/Applications/CopilotUsageBar.app/Contents/MacOS/CopilotUsageBar --check

prints exactly what the panel would show, so you can compare it against github.com/settings/copilot/features.

How it works

Usage comes from GET https://api.github.com/copilot_internal/user, authenticated with the token from gh auth token. That endpoint is undocumented and may change without notice; everything that knows its shape lives in Sources/CopilotUsageBar/CopilotAPI.swift, so a break is a one-file fix and surfaces as a clean error state rather than a crash.