# hamed-elfayome/claude-usage-tracker architecture

> Architecture diagram of the GitHub repository hamed-elfayome/claude-usage-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamed-elfayome/claude-usage-tracker
- Repository: https://github.com/hamed-elfayome/claude-usage-tracker

## Overview

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: [`Claude Usage/MenuBar/MenuBarManager.swift`](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/MenuBarManager.swift) (Menu bar coordinator), [`Claude Usage/MenuBar/UsageRefreshCoordinator.swift`](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/UsageRefreshCoordinator.swift) (Refresh coordinator), [`Claude Usage/Shared/Services/ProfileManager.swift`](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/ProfileManager.swift) (Profile manager), [`Claude Usage/Shared/Services/Providers/ProviderRegistry.swift`](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/ProviderRegistry.swift) (Provider registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Menu Bar Experience"]
  node_app["App lifecycle"]
  node_menubar["Menu bar coordinator"]
  node_refresh["Refresh coordinator"]
  node_statusui["Menu bar display"]
  node_popover["Usage popover"]
  node_settings["Setup and settings<br/>[SettingsView.swift]"]
  node_historyview["History charts"]
end

subgraph group_usage["Usage Collection"]
  node_providerregistry["Provider registry"]
  node_anthropic["Anthropic usage provider"]
  node_claudeapi["Claude API service"]
  node_codexprovider["Codex usage provider"]
  node_codexapi["Codex API service"]
end

subgraph group_profiles["Profiles and State"]
  node_profilemanager["Profile manager"]
  node_profilestore[("Profile storage<br/>[ProfileStore.swift]")]
  node_keystore[("Credential keychain")]
  node_history["Usage history"]
end

subgraph group_integrations["Developer Integrations"]
  node_hookserver["HUD hook server"]
  node_sessionstore[("HUD session state")]
  node_hud["Notch activity HUD"]
  node_statusline["Terminal statusline"]
end

subgraph group_automation["Automation and Alerts"]
  node_autostart["Session automation"]
  node_notifications["Threshold notifications"]
end

node_user(("User"))
node_claude{{"Anthropic services"}}
node_openai{{"OpenAI services"}}
node_claudecode{{"Claude Code CLI"}}
node_notificationcenter{{"macOS notifications"}}

node_user -->|"launches"| node_app
node_app -->|"starts"| node_menubar
node_user -->|"interacts"| node_menubar
node_menubar -->|"requests refresh"| node_refresh
node_refresh -->|"selects provider"| node_providerregistry
node_providerregistry -->|"dispatches"| node_anthropic
node_providerregistry -->|"dispatches"| node_codexprovider
node_anthropic -->|"fetches usage"| node_claudeapi
node_claudeapi -->|"requests usage"| node_claude
node_codexprovider -->|"fetches usage"| node_codexapi
node_codexapi -->|"requests usage"| node_openai
node_menubar -->|"reads profiles"| node_profilemanager
node_profilemanager -->|"persists profiles"| node_profilestore
node_profilemanager -->|"stores credentials"| node_keystore
node_user -->|"configures"| node_settings
node_settings -->|"manages profiles"| node_profilemanager
node_menubar -->|"updates display"| node_statusui
node_user -->|"views usage"| node_popover
node_menubar -->|"opens"| node_popover
node_refresh -->|"records usage"| node_history
node_historyview -->|"reads history"| node_history
node_claudecode -.->|"sends activity"| node_hookserver
node_hookserver -->|"updates sessions"| node_sessionstore
node_hud -->|"observes sessions"| node_sessionstore
node_statusline -.->|"reads usage"| node_claudeapi
node_autostart -.->|"starts session"| node_claude
node_refresh -->|"checks thresholds"| node_notifications
node_notifications -->|"delivers alerts"| node_notificationcenter

click node_app "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/App/ClaudeUsageTrackerApp.swift"
click node_menubar "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/MenuBarManager.swift"
click node_refresh "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/UsageRefreshCoordinator.swift"
click node_statusui "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/StatusBarUIManager.swift"
click node_popover "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/PopoverContentView.swift"
click node_settings "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Views/SettingsView.swift"
click node_providerregistry "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/ProviderRegistry.swift"
click node_anthropic "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/Anthropic/AnthropicUsageProvider.swift"
click node_claudeapi "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/ClaudeAPIService.swift"
click node_codexprovider "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/Codex/CodexUsageProvider.swift"
click node_codexapi "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/Codex/CodexAPIService.swift"
click node_profilemanager "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/ProfileManager.swift"
click node_profilestore "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Storage/ProfileStore.swift"
click node_keystore "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/KeychainService.swift"
click node_history "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/UsageHistoryService.swift"
click node_historyview "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Views/Settings/Profile/UsageHistoryView.swift"
click node_hookserver "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/NotchHUD/NotchHookServer.swift"
click node_sessionstore "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/NotchHUD/NotchSessionStore.swift"
click node_hud "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/NotchHUD/NotchHUDController.swift"
click node_statusline "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/StatuslineService.swift"
click node_autostart "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/AutoStartSessionService.swift"
click node_notifications "https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/NotificationManager.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_menubar,node_refresh,node_statusui,node_popover,node_settings,node_historyview,node_user toneBlue
class node_providerregistry,node_anthropic,node_claudeapi,node_codexprovider,node_codexapi toneAmber
class node_profilemanager,node_profilestore,node_keystore,node_history toneMint
class node_hookserver,node_sessionstore,node_hud,node_statusline toneRose
class node_autostart,node_notifications,node_claude,node_openai,node_claudecode,node_notificationcenter toneIndigo
```

## Components

### Menu Bar Experience

- [App lifecycle](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/App/ClaudeUsageTrackerApp.swift): `Claude Usage/App/ClaudeUsageTrackerApp.swift`
- [Menu bar coordinator](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/MenuBarManager.swift): `Claude Usage/MenuBar/MenuBarManager.swift`
- [Refresh coordinator](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/UsageRefreshCoordinator.swift): `Claude Usage/MenuBar/UsageRefreshCoordinator.swift`
- [Menu bar display](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/StatusBarUIManager.swift): `Claude Usage/MenuBar/StatusBarUIManager.swift`
- [Usage popover](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/PopoverContentView.swift): `Claude Usage/MenuBar/PopoverContentView.swift`
- [Setup and settings](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Views/SettingsView.swift): `Claude Usage/Views/SettingsView.swift`
- [History charts](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Views/Settings/Profile/UsageHistoryView.swift): `Claude Usage/Views/Settings/Profile/UsageHistoryView.swift`

### Usage Collection

- [Provider registry](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/ProviderRegistry.swift): `Claude Usage/Shared/Services/Providers/ProviderRegistry.swift`
- [Anthropic usage provider](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/Anthropic/AnthropicUsageProvider.swift): `Claude Usage/Shared/Services/Providers/Anthropic/AnthropicUsageProvider.swift`
- [Claude API service](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/ClaudeAPIService.swift): `Claude Usage/Shared/Services/ClaudeAPIService.swift`
- [Codex usage provider](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/Codex/CodexUsageProvider.swift): `Claude Usage/Shared/Services/Providers/Codex/CodexUsageProvider.swift`
- [Codex API service](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/Providers/Codex/CodexAPIService.swift): `Claude Usage/Shared/Services/Providers/Codex/CodexAPIService.swift`

### Profiles and State

- [Profile manager](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/ProfileManager.swift): `Claude Usage/Shared/Services/ProfileManager.swift`
- [Profile storage](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Storage/ProfileStore.swift): `Claude Usage/Shared/Storage/ProfileStore.swift`
- [Credential keychain](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/KeychainService.swift): `Claude Usage/Shared/Services/KeychainService.swift`
- [Usage history](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/UsageHistoryService.swift): `Claude Usage/Shared/Services/UsageHistoryService.swift`

### Developer Integrations

- [HUD hook server](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/NotchHUD/NotchHookServer.swift): `Claude Usage/Shared/Services/NotchHUD/NotchHookServer.swift`
- [HUD session state](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/NotchHUD/NotchSessionStore.swift): `Claude Usage/Shared/Services/NotchHUD/NotchSessionStore.swift`
- [Notch activity HUD](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/MenuBar/NotchHUD/NotchHUDController.swift): `Claude Usage/MenuBar/NotchHUD/NotchHUDController.swift`
- [Terminal statusline](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/StatuslineService.swift): `Claude Usage/Shared/Services/StatuslineService.swift`

### Automation and Alerts

- [Session automation](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/AutoStartSessionService.swift): `Claude Usage/Shared/Services/AutoStartSessionService.swift`
- [Threshold notifications](https://github.com/hamed-elfayome/claude-usage-tracker/blob/main/Claude%20Usage/Shared/Services/NotificationManager.swift): `Claude Usage/Shared/Services/NotificationManager.swift`

### Other components

- **User**
- **Anthropic services**
- **OpenAI services**
- **Claude Code CLI**
- **macOS notifications**

## Connections

- 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