hamed-elfayome/Claude-Usage-Tracker

Claude Usage Tracker is a macOS menu bar application that monitors and displays usage statistics for AI coding assistants, specifically supporting Anthropic Claude and OpenAI Codex. It provides multi-profile management, real-time session tracking via a Dynamic Island HUD, and detailed API billing insights with customizable visual indicators. The system handles credential security through macOS Keychain integration and supports automatic updates and extensive internationalization.

24 changes.

This period covers the initial release and rapid evolution of the Claude Usage Tracker macOS application, expanding from a single-provider usage monitor to a multi-profile, multi-provider system supporting OpenAI Codex and Anthropic. The work focused on building a robust architecture with modular services, secure keychain storage, and a customizable menu bar interface, while simultaneously adding comprehensive internationalization for over a dozen languages and integrating automatic update and notch HUD capabilities.

13 changes.

This period focused on expanding the application's global reach by adding comprehensive localization support for Japanese, Korean, Chinese, Turkish, Ukrainian, Brazilian Portuguese, and Vietnamese. Concurrently, the project introduced a new Notch HUD feature that displays real-time Claude Code session activity via a secure, read-only hook system, enhancing the user experience on macOS devices with dynamic islands or notched displays.

Users can now see the app interface in Brazilian Portuguese. This change adds a new Localizable.strings file for the pt-BR locale, providing translations for all UI elements including settings, menu bar metrics, usage status alerts, and the setup wizard.

Claude Usage/Resources/pt-BR.lproj · high confidence

The application now includes a comprehensive set of English localization strings (Localizable.strings) covering the main interface, settings, menu bar metrics, usage status alerts, and setup wizard instructions. This enables the app to display user-facing text consistently and prepares the codebase for future multi-language support.

Claude Usage/Resources/en.lproj · high confidence

The application now supports Turkish, adding a complete set of localized strings for the user interface, settings, menu bar, and setup wizard.

Claude Usage/Resources/tr.lproj · high confidence

The application now supports Vietnamese, adding a complete set of translated strings for the user interface, including menus, settings, usage status messages, and the setup wizard. This allows Vietnamese-speaking users to interact with the app in their native language.

Claude Usage/Resources/vi.lproj · high confidence

The app now includes complete user-interface translations for German (de), French (fr), Italian (it), and Portuguese (pt). These new language packs cover all existing interface elements, including the setup wizard, settings, menu bar metrics, and usage status messages, allowing users in these regions to interact with the tracker in their native language.

(repo-wide) · high confidence

The application now supports the Korean language, providing translated strings for the main interface, settings, menu bar metrics, multi-profile management, and usage status notifications.

Claude Usage/Resources/ko.lproj · high confidence

The application now supports Simplified Chinese, with a new Localizable.strings file providing translations for the main interface, settings, menu bar indicators, usage status messages, and setup wizard steps.

Claude Usage/Resources/zh-ch.lproj · high confidence

Users can now see the application interface in Spanish. This change introduces a new Localizable.strings file for the es.lproj resource directory, providing translations for the app name, settings categories (such as API billing and session management), menu bar metrics (including weekly usage and model-specific tracking for Opus, Sonnet, and Fable), notification alerts, and error messages.

Claude Usage/Resources/es.lproj · high confidence

The application now supports Traditional Chinese (zh-Hant) for its user interface. This change adds a complete set of localized strings for the main window, settings panels, menu bar indicators, usage status messages, and setup wizards, allowing users to interact with the Claude Usage Tracker in Traditional Chinese.

Claude Usage/Resources/zh-Hant.lproj · high confidence

Users can now see the application interface in Ukrainian. This change adds a new localization file (uk.lproj/Localizable.strings) containing translations for all UI elements, including settings, menu bar indicators, usage status messages, and the setup wizard.

Claude Usage/Resources/uk.lproj · high confidence

A new Xcode scheme file has been added for the 'Claude Usage' target, configuring build, test, launch, profile, analyze, and archive actions. This enables developers to run, test, and debug the application directly within Xcode using the specified build configurations and debugger settings.

Claude Usage.xcodeproj/xcshareddata · high confidence

The app now supports 15 languages, including English, Spanish, French, German, Italian, Portuguese, Brazilian Portuguese, Japanese, Korean, Simplified Chinese, Traditional Chinese, Ukrainian, Turkish, and Vietnamese. Users can switch the interface language in Settings, with the app automatically detecting the system language on first launch and persisting the selection across restarts.

Claude Usage/Shared/Localization · high confidence

This release introduces a multi-provider architecture that allows tracking OpenAI Codex usage alongside Anthropic, with profiles now able to select their provider and automatically refreshing tokens. It adds per-profile terminal launchers (\claude-\<profile\>\) that run Claude Code with isolated \CLAUDE\_CONFIG\_DIR\ logins, enabling separate usage tracking per account. Vietnamese (Tiếng Việt) is now available as the 14th interface language. The update also fixes several reliability issues: the popover now appears over full-screen apps, the Dynamic Island HUD targets the built-in notch correctly, Cloudflare challenges no longer trigger false credential expiration errors, and macOS 26 multi-profile crashes are resolved. Additionally, the obsolete peak hours indicator has been removed, and the keychain migration now correctly falls back to the file-based login keychain on unentitled Developer ID builds.

(repo-wide) · high confidence

The app now displays version numbers dynamically using build system variables instead of hardcoded values, ensuring accurate version tracking. Additionally, Sparkle automatic updates have been enabled, allowing the application to check for and install updates automatically in the background with gentle reminders.

Claude Usage/Resources · high confidence

Introduces the first version of Claude Usage Tracker, a macOS menu bar application that monitors and displays usage statistics for Claude Code. The app features a native menu bar interface with a popover dashboard showing session and weekly usage limits, automatic background refresh, and configurable notification alerts for usage thresholds. It includes a setup wizard for configuring API access via session keys, persistent storage for preferences and usage data, and a settings interface for managing API credentials, refresh intervals, and notification preferences.

ClaudeUsageTracker · high confidence

A new Heads-Up Display (HUD) now appears in the Mac notch (or as a floating pill on non-notched displays) to show the status of active Claude Code sessions. The HUD presents a compact view with a status icon, project name, and session count, which expands into a detailed list showing all live sessions, their current tasks or last prompts, and elapsed time. The controller intelligently targets the built-in notched display when available, ensuring the HUD stays anchored to the MacBook notch rather than floating on the primary screen in multi-monitor setups.

Claude Usage/MenuBar/NotchHUD · high confidence

The app now features a centralized error management system that standardizes how errors are reported, logged, and resolved. Users will see structured alerts with specific recovery suggestions and copyable error codes for support tickets, rather than generic failure messages. The system automatically handles transient issues like network timeouts or API rate limits by retrying operations with exponential backoff, while non-recoverable errors (such as invalid session keys) prompt users to update their settings. This change improves stability by masking temporary glitches and provides clearer guidance when configuration or connectivity issues occur.

Claude Usage/Shared/ErrorHandling · high confidence

This change adds the foundational utility classes and constants that power the application's usage tracking and interface logic. It introduces a centralized \Constants\ enum defining configuration keys, API endpoint bases (Claude, Console, Codex), and timing thresholds for notifications and prompts. It also adds \SessionKeyValidator\ for secure session key validation, \URLBuilder\ for safe API URL construction, \UsageStatusCalculator\ for determining usage levels with pace-aware projections, and \PaceStatus\ for a 6-tier urgency spectrum in the menu bar. Additionally, it includes \FunnyNameGenerator\ for profile naming and establishes the new \Claude Usage/Shared/Utilities\ module structure.

Claude Usage/Shared/Utilities · high confidence

Users can now assign global keyboard shortcuts to toggle the popover, refresh usage data, open settings, and switch between profiles, with these bindings persisted in the app's shared data store. Additionally, profile credentials (session keys and API tokens) are now securely stored in the macOS Keychain rather than plaintext on disk, with an automatic migration process that moves existing credentials from the local plist to the Keychain while verifying writes to prevent data loss.

Claude Usage/Shared/Storage · high confidence

The application now includes Japanese (ja) localization, providing translated strings for the main interface, settings, menu bar metrics, usage status messages, and setup wizard instructions.

Claude Usage/Resources/ja.lproj · high confidence

The Settings window now includes several new dedicated views under the App section: an About page displaying version, creator credits, and GitHub links; a Language selector that requires an app restart to apply; a Debug Network Log viewer for inspecting API requests; a Manage Profiles interface for configuring multi-profile display modes and icon styles; a Mobile App 'Coming Soon' page to collect anonymous interest signals; and a Notch HUD settings panel to toggle the Dynamic Island integration and manage hook installation status.

Claude Usage/Views/Settings · high confidence

The Settings view now uses a centralized design system (DesignTokens, SettingsColors) to provide consistent typography, spacing, and styling across all settings sections. This introduces a suite of reusable UI components including SettingsCard, SettingsSectionCard, SettingToggle (with beta/pro/new badges), SettingsButton, and IconStylePicker for customizing menu bar icon appearances. Additionally, users can now configure metric-specific display options (session, week, API) via MetricIconCard, select profiles in multi-profile mode via ProfileSelectionRow, and record global keyboard shortcuts using the new ShortcutRecorderView.

Claude Usage/Views/Settings/Components · high confidence

This change introduces several new extension files to the shared codebase. Color+AppColors.swift and Color+Extensions.swift add support for adaptive green colors that adjust for light/dark modes and provide hex string conversion utilities. NSWindow+FullScreenSpaces.swift enables menu bar windows to display across all Spaces, including full-screen spaces of other applications. Notification+Extensions.swift defines new notification names for menu bar icon configuration changes, credential updates, setup wizard triggers, display mode changes, multi-profile configuration updates, auto-switch profile triggers, and notch HUD settings. Date+Extensions.swift was moved and updated to support 24-hour time format detection, improved day/hour remaining calculations, and date rounding to the nearest minute. UserDefaults+Extensions.swift was also moved to the new location.

Claude Usage/Shared/Extensions · high confidence

The Settings \> Credentials section now includes dedicated views for managing different account types: APIBillingView for API console billing and session key tracking, CLIAccountView for syncing and displaying CLI account details and scopes, and CodexAccountView for auto-detecting or manually entering OpenAI Codex credentials. Additionally, ConsoleAuthWebView provides a WKWebView-based authentication flow with session expiry tracking and cookie polling to handle login on macOS 26+.

Claude Usage/Views/Settings/Credentials · high confidence

This change introduces a comprehensive set of new data models in the Shared/Models layer to support expanded usage tracking and multi-profile capabilities. Key additions include APIUsage for tracking API console billing credits with per-source and per-model cost breakdowns, and ClaudeUsage extended with weekly usage fields for specific models (Opus, Sonnet, Design, Fable) plus extra usage and overage balance tracking. The Profile model now supports multiple providers (Anthropic, Codex) with provider-specific credential and usage data storage. New models like MenuBarIconConfig and StatuslineElementColors enable granular customization of menu bar icons and statusline colors, while UsageHistory and DateRangeSelection support interactive usage history charts with filtering. The change also includes ClaudeCodeSession for live CLI session tracking in the notch HUD, NetworkRequestLog for debugging, and ProviderDescriptor for declarative provider capabilities. Backward-compatible decoding is implemented in ClaudeUsage to prevent profile data loss during upgrades.

Claude Usage/Shared/Models · high confidence

The app now includes an in-app feedback prompt that appears after seven days of installation, allowing users to voluntarily submit their role, contact information, and suggestions via a dedicated popup view. Additionally, a new API Settings view enables users to configure billing tracking by entering a session key and selecting an organization, with built-in validation and status feedback. The settings interface has also been redesigned with a borderless window, custom traffic light buttons, and enhanced visual effects for a more native macOS appearance.

Claude Usage/Views · high confidence

Added new SwiftUI views for the Profile settings area: AppearanceSettingsView lets users customize menu bar icon appearance (monochrome, labels, remaining percentage, time/pace markers) and metric visibility; GeneralSettingsView provides controls for refresh interval, auto-start sessions, notifications with usage thresholds, and per-profile terminal launchers; UsageHistoryView displays interactive usage charts (5h, 24h, 7d, 30d) with billing cycle data and export to JSON/CSV.

Claude Usage/Views/Settings/Profile · high confidence

The Notch HUD now displays real-time Claude Code activity (sessions, prompts, tool usage, and errors) by installing lightweight HTTP hooks into \~/.claude/settings.json. A new loopback-only server receives these events and updates the HUD status, while a dedicated installer manages the hook configuration. The implementation is strictly read-only to prevent security risks, and includes a fix to prevent HTTP 413 errors on large payloads by draining oversized bodies before acknowledging.

Claude Usage/Shared/Services/NotchHUD · high confidence

A new shell script, validate\_localizations.sh, has been added to the scripts directory to ensure consistency across app localization files by comparing key counts and presence in all .lproj directories against the base English file. Concurrently, the postinstall script, which previously removed macOS quarantine attributes from the installed application bundle, has been removed.

scripts · high confidence

The application has been restructured and relaunched (v2.2.1/2.2.2) to support multiple user profiles, automatically syncing credentials from the system Keychain for CLI-based providers to streamline setup. It now includes a 24-hour heartbeat service to track active usage, a monthly "buy-me-a-coffee" support reminder, and in-app prompts for GitHub stars and user feedback. The app also features a headless mode for Remote Desktop scenarios, a configurable Claude Code notch HUD, and Japanese language support.

Claude Usage/App · high confidence

The application's service layer has been refactored to support a multi-provider architecture, introducing protocols for API, notification, and storage services to enable dependency injection. A new \UsageProviderService\ protocol allows for extensible usage data fetching, while \ClaudeAPIService\ now implements a fallback chain that prioritizes the Claude.ai session key, then saved CLI OAuth tokens, and finally system Keychain credentials. This change also includes a new \AutoStartSessionService\ to automatically restart sessions when they reset, and a \KeychainMigrationService\ to securely move session keys from file-based storage to the system Keychain.

Claude Usage/Shared/Services · high confidence

The Xcode project file has been updated to include the Sparkle framework for automatic updates and DynamicNotchKit for the Claude Code notch HUD. The project now references these two Swift packages, adds their respective build files to the main application target, and includes a new unit test target named 'Claude UsageTests'. Additionally, the list of supported localization regions has been expanded to include Vietnamese (vi), Turkish (tr), and several Chinese variants.

Claude Usage.xcodeproj · high confidence

The menu bar now supports multiple Claude profiles simultaneously, displaying a separate status item for each profile in multi-profile mode. The icon rendering engine has been completely rewritten to offer five customizable visual styles (battery, progress bar, percentage only, icon with bar, and compact), along with new indicators for session time markers, pace coloring, and next session times. The popover interface has been updated to show usage data for the selected profile, including provider logos and active profile indicators, while fixing previous crashes related to profile switching and macOS 26 compatibility.

Claude Usage/MenuBar · high confidence

The application's macOS entitlements have been modified to remove the application group configuration, indicating a shift away from shared container usage, while adding explicit permissions for network client access, allowing unsigned executable memory, and disabling library validation. These changes adjust the security profile of the app, likely to support specific runtime behaviors or code signing requirements without relying on app group sharing.

Claude Usage · high confidence

The project workspace has been repaired by adding the missing \contents.xcworkspacedata\ and \WorkspaceSettings.xcsettings\ files. This restores the standard Xcode workspace structure and ensures build compatibility with macOS Sonoma by aligning the project file versioning.

Claude Usage.xcodeproj/project.xcworkspace · high confidence

Added comprehensive unit tests for the Claude Usage module, covering status level thresholds (safe, moderate, critical), legacy JSON decoding tolerance to prevent profile wipes on upgrade, Codex provider authentication and usage parsing, date extension formatting, macOS full-screen space behavior, Notch HUD HTTP parsing and session store logic, hook installer settings management, and secure profile credential storage in the keychain.

Claude UsageTests · high confidence

The project now includes DynamicNotchKit version 1.1.0 and Sparkle version 2.8.1 as resolved dependencies. DynamicNotchKit is added to support the Claude Code notch HUD, while Sparkle is included to enable automatic update functionality.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 67 → 66 (-1.3)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 87 → 82 (-5.1)
• Architecture 92 → 94 (+1.8)
• Maturity 62 → 63 (+0.1)
• Readiness 67 → 65 (-1.8)
• Security 63 → 63 (+0.0)

• Hotspot: Claude Usage/MenuBar/StatusBarUIManager.swift (Claude Usage/MenuBar/StatusBarUIManager.swift)
• Hotspot: Claude Usage/Shared/Services/StatuslineService.swift (Claude Usage/Shared/Services/StatuslineService.swift)
• Off-boarding risk: anonymized user #1
• Repeated repair: Claude Usage/MenuBar/PopoverContentView.swift (Claude Usage/MenuBar/PopoverContentView.swift)

• APIBillingView.body (cognitive 23) (Claude Usage/Views/Settings/Credentials/APIBillingView.swift)
• APIBillingView.body (cyclomatic 19) (Claude Usage/Views/Settings/Credentials/APIBillingView.swift)
• CLIAccountView.body (cognitive 40) (Claude Usage/Views/Settings/Credentials/CLIAccountView.swift)
• CLIAccountView.body (cyclomatic 20) (Claude Usage/Views/Settings/Credentials/CLIAccountView.swift)
• ClaudeCodeView.body (cognitive 29) (Claude Usage/Views/Settings/App/ClaudeCodeView.swift)
• ClaudeCodeView.body (cyclomatic 18) (Claude Usage/Views/Settings/App/ClaudeCodeView.swift)
• ClaudeCodeView.multiColorPreview (cognitive 103) (Claude Usage/Views/Settings/App/ClaudeCodeView.swift)
• ClaudeCodeView.multiColorPreview (cyclomatic 74) (Claude Usage/Views/Settings/App/ClaudeCodeView.swift)
• Duplicated block (10 lines × 2) (Claude Usage/Views/Settings/Components/UsageCharts.swift)
• Duplicated block (10 lines × 2) (Claude Usage/Views/Settings/Components/UsageCharts.swift)
• Duplicated block (10 lines × 2) (Claude Usage/Views/Settings/Credentials/APIBillingView.swift)
• Duplicated block (10 lines × 2) (Claude Usage/Views/Settings/Profile/AppearanceSettingsView.swift)
• Duplicated block (10 lines × 2) (Claude Usage/Views/Settings/Profile/UsageHistoryView.swift)
• Duplicated block (10 lines × 2) (Claude Usage/Views/SettingsView.swift)
• Duplicated block (10 lines × 2) (Claude Usage/Views/SettingsView.swift)
• Duplicated block (10 lines × 2) (Claude Usage/Views/SetupWizardView.swift)
• Duplicated block (10 lines × 3) (Claude Usage/Views/Settings/App/UpdatesSettingsView.swift)
• Duplicated block (10 lines × 4) (Claude Usage/Views/Settings/Credentials/APIBillingView.swift)
• Duplicated block (10 lines × 4) (Claude Usage/Views/Settings/Credentials/APIBillingView.swift)
• Duplicated block (11 lines × 2) (Claude Usage/MenuBar/PopoverContentView.swift)
• …and 99 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

hamed-elfayome/Claude-Usage-Tracker was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.