How endikk/claudy works
Claudy is a macOS desktop widget for live Claude account quotas, local token-use detail, and Claude Code listening-port management. The main workflow refreshes account usage and transcript-derived detail into a shared view model, then presents it through the selected floating-card, menu-bar, or notch interface. A separate Ports workflow scans listening processes and supports terminating them. The README documents these capabilities; unsampled subsystem wiring is shown only where the README or SOURCE INDEX supports it.
Main entry points: UsageViewModel.swift Usage view model · AppDelegate.swift App lifecycle · PortsViewModel.swift Ports view model · FullView.swift Full widget view
Components 25
App and placement
- App lifecycle
Claudy/App/AppDelegate.swift - Placement rules
Claudy/Models/Placement.swift - Floating panel
Claudy/App/FloatingPanel.swift - Menu bar controller
Claudy/App/MenuBarController.swift - Notch controller
Claudy/App/NotchController.swift - Update checker
Claudy/Services/UpdateChecker.swift
Usage and account data
- Usage view model
Claudy/ViewModels/UsageViewModel.swift - Usage data source
Claudy/Services/UsageDataSource.swift - Anthropic account client
Claudy/Services/ClaudeAccountClient.swift - OAuth sign-in
Claudy/Services/ClaudeOAuth.swift - Account loader
Claudy/Services/AccountLoader.swift - Claude local data
Claudy/Services/ClaudeHome.swift - Transcript scanner
Claudy/Services/TranscriptScanner.swift - Usage aggregator
Claudy/Services/UsageAggregator.swift
Claude Code ports
- Ports view model
Claudy/ViewModels/PortsViewModel.swift - Port scanner
Claudy/Services/PortScanner.swift - Process table
Claudy/Services/ProcessTable.swift - Port reaper
Claudy/Services/PortReaper.swift
Views and interaction
- Full widget view
Claudy/Views/FullView.swift - Menu bar view
Claudy/Views/MenuBarView.swift - Notch view
Claudy/Views/NotchView.swift - Ports view
Claudy/Views/PortsView.swift - Theme and mascot
Claudy/Theme/Theme.swift
Other components
- Mac user
- Anthropic API
Connections 30
- Mac user → App lifecycle: launches
- App lifecycle → Usage view model: creates
Claudy/App/AppDelegate.swift - App lifecycle → Placement rules: selects placement
Claudy/App/AppDelegate.swift - App lifecycle → Floating panel: shows panel
Claudy/App/AppDelegate.swift - App lifecycle → Menu bar controller: selects display
Claudy/App/AppDelegate.swift - App lifecycle → Notch controller: selects display
Claudy/App/AppDelegate.swift - App lifecycle → Update checker: starts checks
Claudy/App/AppDelegate.swift - Usage view model → Usage data source: refreshes through
Claudy/ViewModels/UsageViewModel.swift - Usage data source → Anthropic account client: loads quotas
- Anthropic account client → Anthropic API: fetches usage
Claudy/Services/ClaudeAccountClient.swift - Usage view model → OAuth sign-in: signs in
Claudy/ViewModels/UsageViewModel.swift - Account loader → Claude local data: reads account data
Claudy/Services/AccountLoader.swift - Transcript scanner → Claude local data: reads local transcripts
Claudy/Services/TranscriptScanner.swift - Usage aggregator → Transcript scanner: aggregates detail
- Usage view model → Anthropic account client: uses account client
Claudy/ViewModels/UsageViewModel.swift - Ports view model → Port scanner: scans ports
Claudy/ViewModels/PortsViewModel.swift - Ports view model → Port reaper: kills process
Claudy/ViewModels/PortsViewModel.swift - Port scanner → Process table: inspects processes
Claudy/Services/PortScanner.swift - Port reaper → Process table: checks process
Claudy/Services/PortReaper.swift - Full widget view → Usage view model: renders usage
Claudy/Views/FullView.swift - Full widget view → Ports view model: renders ports tab
Claudy/Views/FullView.swift - Menu bar view → Usage view model: renders usage
Claudy/Views/MenuBarView.swift - Notch view → Usage view model: renders usage
Claudy/Views/NotchView.swift - Ports view → Ports view model: renders port state
- Menu bar controller → Menu bar view: hosts view
Claudy/App/MenuBarController.swift - Notch controller → Notch view: hosts view
Claudy/App/NotchController.swift - Full widget view → Theme and mascot: uses styling
Claudy/Views/FullView.swift - Menu bar view → Theme and mascot: uses styling
Claudy/Views/MenuBarView.swift - Notch view → Theme and mascot: uses styling
Claudy/Views/NotchView.swift - Mac user → Usage view model: requests refresh