How hamed-elfayome/claude-usage-tracker works
Claude Usage Tracker is a native macOS menu-bar app for monitoring Claude and Codex account usage. Users configure credentials and profiles, then the app refreshes provider data and presents limits in menu-bar icons and a popover; optional branches add usage history, alerts, terminal statuslines, and a Claude Code activity HUD. The README documents these capabilities, while sampled source confirms selected orchestration and service behavior; some subsystem links are omitted where wiring was not shown.
Main entry points: MenuBarManager.swift Menu bar coordinator · UsageRefreshCoordinator.swift Refresh coordinator · ProfileManager.swift Profile manager · ProviderRegistry.swift Provider registry
Components 27
Menu Bar Experience
- App lifecycle
Claude Usage/App/ClaudeUsageTrackerApp.swift - Menu bar coordinator
Claude Usage/MenuBar/MenuBarManager.swift - Refresh coordinator
Claude Usage/MenuBar/UsageRefreshCoordinator.swift - Menu bar display
Claude Usage/MenuBar/StatusBarUIManager.swift - Usage popover
Claude Usage/MenuBar/PopoverContentView.swift - Setup and settings
Claude Usage/Views/SettingsView.swift - History charts
Claude Usage/Views/Settings/Profile/UsageHistoryView.swift
Usage Collection
- Provider registry
Claude Usage/Shared/Services/Providers/ProviderRegistry.swift - Anthropic usage provider
Claude Usage/Shared/Services/Providers/Anthropic/AnthropicUsageProvider.swift - Claude API service
Claude Usage/Shared/Services/ClaudeAPIService.swift - Codex usage provider
Claude Usage/Shared/Services/Providers/Codex/CodexUsageProvider.swift - Codex API service
Claude Usage/Shared/Services/Providers/Codex/CodexAPIService.swift
Profiles and State
- Profile manager
Claude Usage/Shared/Services/ProfileManager.swift - Profile storage
Claude Usage/Shared/Storage/ProfileStore.swift - Credential keychain
Claude Usage/Shared/Services/KeychainService.swift - Usage history
Claude Usage/Shared/Services/UsageHistoryService.swift
Developer Integrations
- HUD hook server
Claude Usage/Shared/Services/NotchHUD/NotchHookServer.swift - HUD session state
Claude Usage/Shared/Services/NotchHUD/NotchSessionStore.swift - Notch activity HUD
Claude Usage/MenuBar/NotchHUD/NotchHUDController.swift - Terminal statusline
Claude Usage/Shared/Services/StatuslineService.swift
Automation and Alerts
- Session automation
Claude Usage/Shared/Services/AutoStartSessionService.swift - Threshold notifications
Claude Usage/Shared/Services/NotificationManager.swift
Other components
- User
- Anthropic services
- OpenAI services
- Claude Code CLI
- macOS notifications
Connections 28
- User → App lifecycle: launches
- App lifecycle → Menu bar coordinator: starts
- User → Menu bar coordinator: interacts
- Menu bar coordinator → Refresh coordinator: requests refresh
- Refresh coordinator → Provider registry: selects provider
- Provider registry → Anthropic usage provider: dispatches
- Provider registry → Codex usage provider: dispatches
- Anthropic usage provider → Claude API service: fetches usage
- Claude API service → Anthropic services: requests usage
- Codex usage provider → Codex API service: fetches usage
- Codex API service → OpenAI services: requests usage
- Menu bar coordinator → Profile manager: reads profiles
- Profile manager → Profile storage: persists profiles
- Profile manager → Credential keychain: stores credentials
- User → Setup and settings: configures
- Setup and settings → Profile manager: manages profiles
- Menu bar coordinator → Menu bar display: updates display
- User → Usage popover: views usage
- Menu bar coordinator → Usage popover: opens
- Refresh coordinator → Usage history: records usage
- History charts → Usage history: reads history
- Claude Code CLI → HUD hook server: sends activity
- HUD hook server → HUD session state: updates sessions
- Notch activity HUD → HUD session state: observes sessions
- Terminal statusline → Claude API service: reads usage
- Session automation → Anthropic services: starts session
- Refresh coordinator → Threshold notifications: checks thresholds
- Threshold notifications → macOS notifications: delivers alerts