A multi-platform app (macOS + iOS) that monitors your Claude Code API usage in real-time.

Archived: This project was archived on 2026-05-01 and is no longer maintained. Releases and source code remain available as-is, but no further feature work, fixes, support, or releases are planned.

Multi-platform app that monitors Claude Code API usage in real-time. Tracks session (5-hour) and weekly (7-day) rate limits for Opus and Sonnet models, plus token usage and cost from local logs.

Platforms:

• macOS 15+: Menu bar app with local notifications and auto-updates
• iOS 18+: Dashboard app with local notifications, widgets, and Live Activity

Core (macOS & iOS):

• Real-time usage monitoring with auto-refresh (1, 2, 5, or 15 min intervals)
• Session (5hr) and weekly (7-day) rate limits for Opus and Sonnet
• Token usage tracking with cost calculation (today and last 30 days)
• Local threshold alerts at 25%, 50%, 75%, and 100%, plus reset and extra-usage alerts
• Color-coded indicators (green/orange/red) and countdown timers
• Native Swift/SwiftUI with Claude brand colors

macOS Only:

• Menu bar app with dynamic color-coded icon
• Launch at login option
• Auto-updates via Sparkle
• Orange badge when update available
• Keyboard shortcuts (⌘, for Settings)

iOS Only:

• Home Screen widgets (Small, Medium, Large)
• Lock Screen widget
• Live Activity for Dynamic Island
• Full dashboard app with tabs

• macOS: 15.0+ (Sequoia), Claude CLI authenticated
• iOS: 18.0+, iPhone with Dynamic Island (for Live Activity)
• Active Claude Code subscription

macOS:

1. Download AgentUsage.zip from Releases
2. Move AgentUsage.app to Applications
3. Open AgentUsage. Because current releases are ad-hoc signed, macOS will initially block the app as coming from an unidentified developer.
4. Open System Settings → Privacy & Security, scroll to the security message for AgentUsage, click Open Anyway, then confirm Open. See Apple's guidance.
5. AgentUsage appears in the menu bar.

iOS: Currently in development. Build from source (see below).

Prerequisites:

# Install and authenticate Claude CLI (creates ~/.claude/.credentials.json)
claude auth login

Building from Source:

git clone https://github.com/tartinerlabs/AgentUsage.git
cd AgentUsage
open AgentUsage.xcodeproj
# Select AgentUsage for macOS/iOS/iPadOS, or AgentUsageWidgetsExtension for widgets
# Press ⌘B to build, ⌘R to run

# Or via command line:
xcodebuild -project AgentUsage.xcodeproj -scheme AgentUsage -configuration Release build

macOS:

• Click menu bar icon to view Session (5hr), Opus, and Sonnet usage with reset timers
• Icon color indicates status: Green (on track), Orange (75-89%), Red (≥90%)
• Access Refresh, Settings (⌘,), About, and Quit from menu

iOS:

• Dashboard tab shows usage stats
• Add widgets: Long-press Home Screen → "+" → "AgentUsage"
• Lock Screen widget: Customize Lock Screen → widget area

Token Usage:

• Analyzes local JSONL logs (~/.claude/projects/) for token counts and costs
• Tracks input, output, cache creation/read tokens for all Claude models
• Shows today and last 30 days usage with Anthropic pricing
• All processing is local

Settings (macOS - ⌘,):

• Refresh: Manual, 1, 2, 5 (default), or 15 minutes
• Notifications: Threshold alerts (25%, 50%, 75%, 100%) and reset notifications
• Launch at Login: Auto-start on macOS startup
• Updates: Manual check or automatic background checks (orange badge when available)

Settings (iOS):

• Refresh intervals, usage notifications, and version info via Settings tab
• iOS alerts are best-effort and are evaluated when the device receives a fresh Mac-synced snapshot during foreground or background refresh

Credentials:

• Reads ~/.claude/.credentials.json for API access
• Token usage from ~/.claude/projects/ JSONL logs
• Manual file selection if not found

MVVM with Swift Actors for thread safety, @Observable for reactive UI, and async/await concurrency.

Credentials not found: Run claude auth login to authenticate

Unauthorized error: Re-authenticate with claude auth login

App not in menu bar: Check Activity Monitor for "AgentUsage" and restart if needed

macOS cannot verify the developer: Follow the Open Anyway steps under Installation. Do not disable Gatekeeper globally.

Token usage zero: Verify logs exist at ~/.claude/projects/ (created when using Claude Code)

Structure: AgentUsage/ (multiplatform app), AgentUsageWidgets/ (iOS widgets and Live Activity), AgentUsageTests/ and AgentUsageUITests/ (multiplatform tests), AgentUsageKit/ (shared package)

Build:

xcodebuild -project AgentUsage.xcodeproj -scheme AgentUsage -configuration Release build
xcodebuild -project AgentUsage.xcodeproj -scheme AgentUsage test

No data collection or transmission. All processing is local. Reads credentials from ~/.claude/.credentials.json. HTTPS API requests only. Sandbox disabled for ~/.claude/ access.

Stack: Swift/SwiftUI, macOS 15+, iOS 18+, MVVM + Actors

Updates: Sparkle 2.8.1 (macOS)

Data: Anthropic OAuth API for rate limits, local JSONL logs for tokens, Anthropic pricing

Releases: Manually triggered through GitHub Actions. Archives are Developer ID-signed, Apple-notarised, and Sparkle EdDSA signed; an ad-hoc-signed fallback path remains available. See RELEASING.md and releases.

This project is archived and no longer accepts support requests. Existing issues and releases remain available for reference.

Releases: https://github.com/tartinerlabs/AgentUsage/releases