AI Usage Tracker

AI Usage Tracker is a native macOS app with WidgetKit desktop widgets for monitoring AI coding assistant usage across Codex and Claude Code.

The product display name is AI Usage Tracker. Xcode targets, bundle identifiers, app-group storage, and release artifacts use the AIUsageTracker identifier family.

The app is designed around a simple rule: the macOS app refreshes quota data, then the widgets render the latest stored snapshot. Widgets never run shell commands directly, which keeps WidgetKit integration reliable while still allowing the main app to execute local provider tools.

What it does

• Reads quota data from scripts under Application Support, from codex-quota / claude-quota on PATH, from local Codex session metadata, from ccusage for Claude Code, or from a custom shell command you configure.
• Displays a dark compact dashboard in the macOS app.
• Ships square, rectangular, and large WidgetKit widgets.
• Uses provider-specific visual themes for Codex and Claude Code.
• Builds and packages as a universal macOS app: arm64 + x86_64.

Install

Download the latest DMG from GitHub Releases, open it, and drag AIUsageTracker.app into /Applications.

If you previously installed an older build, delete it from /Applications before dragging the new app into place so Launch Services does not open a stale bundle. In macOS widget editing mode, search for AI Usage Tracker and add the widget to the desktop.

If the widget does not appear immediately, open the app once and wait a few seconds. macOS can cache WidgetKit extension registration.

If macOS still does not list it, quit and reopen the app after installing the latest DMG. Development builds must keep App Sandbox enabled for the widget extension so WidgetKit registers it. The main app intentionally stays unsandboxed in local builds so it can run provider scripts and shell helpers.

Provider discovery

In Settings, choose one of the supported providers:

• Codex: runs the first readable script among
  ~/Library/Application Support/AIUsageTracker/codex-quota.py,
  codex-quota.sh, or codex-quota; if none exist, it also checks for an executable codex-quota on PATH. When no quota script is installed but Codex itself is present, AI Usage Tracker falls back to reading the latest local rate_limits entries from ~/.codex.
• Claude Code: runs claude-quota.py, claude-quota.sh, or claude-quota from the same folder if present; otherwise checks for claude-quota on PATH, then runs ccusage --json via /bin/zsh when ccusage is installed.
• Custom: runs a user-supplied shell command.

Create the support folder if needed:

mkdir -p ~/Library/Application\ Support/AIUsageTracker

Paths are resolved from the current user's home directory. No username is hardcoded.

Expected text output:

Codex quota: session 46% (reset 05-12 12:07); weekly 78% (reset 05-15 19:44)
Claude Code usage: current 50% (reset 05-12 12:07); weekly 11% (reset 05-15 19:44)

Expected JSON output:

{
  "currentPercent": 50,
  "weeklyPercent": 11,
  "currentResetAt": "2026-05-12T12:07:00+02:00",
  "weeklyResetAt": "2026-05-15T19:44:00+02:00"
}

Shared snapshot storage

The app saves the latest parsed quota snapshot in the best available shared location:

1. App Group UserDefaults/container: group.com.zer0.aiusagetracker, when a signed build enables the App Group entitlement.
2. Portable fallback file: ~/Library/Application Support/AIUsageTracker/snapshot.json, used for local development and simple unsigned/ad-hoc builds.

The fallback keeps local development usable even without a paid Apple Developer signing identity. For a polished distributable build, configure a real Developer Team and enable the App Group capability for both the app and widget targets. See docs/app-group-entitlements.md.

Development

Requirements:

• macOS 14 or newer
• Xcode
• XcodeGen

Generate the Xcode project:

~/.local/bin/xcodegen generate

Run tests:

xcodebuild test -scheme AIUsageTracker -destination 'platform=macOS,arch=arm64'

Build a universal release app:

xcodebuild build -scheme AIUsageTracker -configuration Release -destination 'generic/platform=macOS'

Create a simple DMG:

scripts/package-dmg.sh

Output: build/package/AIUsageTracker-<MARKETING_VERSION>.dmg (for example AIUsageTracker-0.3.0.dmg). The script wipes packaging Derived Data and runs a clean Release build each time.

The generated DMG is suitable for project releases and local sharing. For broad public distribution, sign and notarize the app with a Developer ID certificate.

Verify architectures:

lipo -info ~/Library/Developer/Xcode/DerivedData/AIUsageTracker-*/Build/Products/Release/AIUsageTracker.app/Contents/MacOS/AIUsageTracker

Release Checklist

• Generate the project with XcodeGen.
• Run the test suite.
• Build Release.
• Package build/package/AIUsageTracker-<version>.dmg.
• Attach the DMG to the matching GitHub Release.

Public distribution still needs:

• Apple Developer ID signing
• notarization
• App Group entitlement enabled in the Apple Developer portal for signed builds

The Codex visual assets in this repository were supplied by the project owner.