# endikk/claudy architecture

> Architecture diagram of the GitHub repository endikk/claudy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/endikk/claudy
- Repository: https://github.com/endikk/claudy

## Overview

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: [`Claudy/ViewModels/UsageViewModel.swift`](https://github.com/endikk/claudy/blob/main/Claudy/ViewModels/UsageViewModel.swift) (Usage view model), [`Claudy/App/AppDelegate.swift`](https://github.com/endikk/claudy/blob/main/Claudy/App/AppDelegate.swift) (App lifecycle), [`Claudy/ViewModels/PortsViewModel.swift`](https://github.com/endikk/claudy/blob/main/Claudy/ViewModels/PortsViewModel.swift) (Ports view model), [`Claudy/Views/FullView.swift`](https://github.com/endikk/claudy/blob/main/Claudy/Views/FullView.swift) (Full widget view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and placement"]
  node_appdelegate["App lifecycle<br/>[AppDelegate.swift]"]
  node_placement["Placement rules<br/>[Placement.swift]"]
  node_floating["Floating panel"]
  node_menubar["Menu bar controller"]
  node_notch["Notch controller"]
  node_updates["Update checker"]
end

subgraph group_usage["Usage and account data"]
  node_viewmodel["Usage view model"]
  node_datasource["Usage data source"]
  node_accountclient["Anthropic account client"]
  node_oauth["OAuth sign-in<br/>[ClaudeOAuth.swift]"]
  node_accountloader["Account loader"]
  node_claudehome["Claude local data<br/>[ClaudeHome.swift]"]
  node_transcripts["Transcript scanner"]
  node_aggregator["Usage aggregator"]
end

subgraph group_ports["Claude Code ports"]
  node_portsvm["Ports view model"]
  node_scanner["Port scanner<br/>[PortScanner.swift]"]
  node_processtable["Process table<br/>[ProcessTable.swift]"]
  node_reaper["Port reaper<br/>[PortReaper.swift]"]
end

subgraph group_presentation["Views and interaction"]
  node_fullview["Full widget view<br/>[FullView.swift]"]
  node_menubarview["Menu bar view<br/>[MenuBarView.swift]"]
  node_notchview["Notch view<br/>[NotchView.swift]"]
  node_portsview["Ports view<br/>[PortsView.swift]"]
  node_theme["Theme and mascot<br/>[Theme.swift]"]
end

node_user(("Mac user"))
node_anthropic{{"Anthropic API"}}

node_user -->|"launches"| node_appdelegate
node_appdelegate -->|"creates"| node_viewmodel
node_appdelegate -->|"selects placement"| node_placement
node_appdelegate -.->|"shows panel"| node_floating
node_appdelegate -->|"selects display"| node_menubar
node_appdelegate -->|"selects display"| node_notch
node_appdelegate -->|"starts checks"| node_updates
node_viewmodel -->|"refreshes through"| node_datasource
node_datasource -.->|"loads quotas"| node_accountclient
node_accountclient -->|"fetches usage"| node_anthropic
node_viewmodel -->|"signs in"| node_oauth
node_accountloader -->|"reads account data"| node_claudehome
node_transcripts -->|"reads local transcripts"| node_claudehome
node_aggregator -.->|"aggregates detail"| node_transcripts
node_viewmodel -->|"uses account client"| node_accountclient
node_portsvm -->|"scans ports"| node_scanner
node_portsvm -->|"kills process"| node_reaper
node_scanner -->|"inspects processes"| node_processtable
node_reaper -->|"checks process"| node_processtable
node_fullview -->|"renders usage"| node_viewmodel
node_fullview -->|"renders ports tab"| node_portsvm
node_menubarview -->|"renders usage"| node_viewmodel
node_notchview -->|"renders usage"| node_viewmodel
node_portsview -.->|"renders port state"| node_portsvm
node_menubar -->|"hosts view"| node_menubarview
node_notch -->|"hosts view"| node_notchview
node_fullview -->|"uses styling"| node_theme
node_menubarview -->|"uses styling"| node_theme
node_notchview -->|"uses styling"| node_theme
node_user -.->|"requests refresh"| node_viewmodel

click node_appdelegate "https://github.com/endikk/claudy/blob/main/Claudy/App/AppDelegate.swift"
click node_placement "https://github.com/endikk/claudy/blob/main/Claudy/Models/Placement.swift"
click node_floating "https://github.com/endikk/claudy/blob/main/Claudy/App/FloatingPanel.swift"
click node_menubar "https://github.com/endikk/claudy/blob/main/Claudy/App/MenuBarController.swift"
click node_notch "https://github.com/endikk/claudy/blob/main/Claudy/App/NotchController.swift"
click node_viewmodel "https://github.com/endikk/claudy/blob/main/Claudy/ViewModels/UsageViewModel.swift"
click node_datasource "https://github.com/endikk/claudy/blob/main/Claudy/Services/UsageDataSource.swift"
click node_accountclient "https://github.com/endikk/claudy/blob/main/Claudy/Services/ClaudeAccountClient.swift"
click node_oauth "https://github.com/endikk/claudy/blob/main/Claudy/Services/ClaudeOAuth.swift"
click node_accountloader "https://github.com/endikk/claudy/blob/main/Claudy/Services/AccountLoader.swift"
click node_claudehome "https://github.com/endikk/claudy/blob/main/Claudy/Services/ClaudeHome.swift"
click node_transcripts "https://github.com/endikk/claudy/blob/main/Claudy/Services/TranscriptScanner.swift"
click node_aggregator "https://github.com/endikk/claudy/blob/main/Claudy/Services/UsageAggregator.swift"
click node_portsvm "https://github.com/endikk/claudy/blob/main/Claudy/ViewModels/PortsViewModel.swift"
click node_scanner "https://github.com/endikk/claudy/blob/main/Claudy/Services/PortScanner.swift"
click node_processtable "https://github.com/endikk/claudy/blob/main/Claudy/Services/ProcessTable.swift"
click node_reaper "https://github.com/endikk/claudy/blob/main/Claudy/Services/PortReaper.swift"
click node_fullview "https://github.com/endikk/claudy/blob/main/Claudy/Views/FullView.swift"
click node_menubarview "https://github.com/endikk/claudy/blob/main/Claudy/Views/MenuBarView.swift"
click node_notchview "https://github.com/endikk/claudy/blob/main/Claudy/Views/NotchView.swift"
click node_portsview "https://github.com/endikk/claudy/blob/main/Claudy/Views/PortsView.swift"
click node_theme "https://github.com/endikk/claudy/blob/main/Claudy/Theme/Theme.swift"
click node_updates "https://github.com/endikk/claudy/blob/main/Claudy/Services/UpdateChecker.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_appdelegate,node_placement,node_floating,node_menubar,node_notch,node_updates,node_user toneBlue
class node_viewmodel,node_datasource,node_accountclient,node_oauth,node_accountloader,node_claudehome,node_transcripts,node_aggregator toneAmber
class node_portsvm,node_scanner,node_processtable,node_reaper,node_anthropic toneMint
class node_fullview,node_menubarview,node_notchview,node_portsview,node_theme toneRose
```

## Components

### App and placement

- [App lifecycle](https://github.com/endikk/claudy/blob/main/Claudy/App/AppDelegate.swift): `Claudy/App/AppDelegate.swift`
- [Placement rules](https://github.com/endikk/claudy/blob/main/Claudy/Models/Placement.swift): `Claudy/Models/Placement.swift`
- [Floating panel](https://github.com/endikk/claudy/blob/main/Claudy/App/FloatingPanel.swift): `Claudy/App/FloatingPanel.swift`
- [Menu bar controller](https://github.com/endikk/claudy/blob/main/Claudy/App/MenuBarController.swift): `Claudy/App/MenuBarController.swift`
- [Notch controller](https://github.com/endikk/claudy/blob/main/Claudy/App/NotchController.swift): `Claudy/App/NotchController.swift`
- [Update checker](https://github.com/endikk/claudy/blob/main/Claudy/Services/UpdateChecker.swift): `Claudy/Services/UpdateChecker.swift`

### Usage and account data

- [Usage view model](https://github.com/endikk/claudy/blob/main/Claudy/ViewModels/UsageViewModel.swift): `Claudy/ViewModels/UsageViewModel.swift`
- [Usage data source](https://github.com/endikk/claudy/blob/main/Claudy/Services/UsageDataSource.swift): `Claudy/Services/UsageDataSource.swift`
- [Anthropic account client](https://github.com/endikk/claudy/blob/main/Claudy/Services/ClaudeAccountClient.swift): `Claudy/Services/ClaudeAccountClient.swift`
- [OAuth sign-in](https://github.com/endikk/claudy/blob/main/Claudy/Services/ClaudeOAuth.swift): `Claudy/Services/ClaudeOAuth.swift`
- [Account loader](https://github.com/endikk/claudy/blob/main/Claudy/Services/AccountLoader.swift): `Claudy/Services/AccountLoader.swift`
- [Claude local data](https://github.com/endikk/claudy/blob/main/Claudy/Services/ClaudeHome.swift): `Claudy/Services/ClaudeHome.swift`
- [Transcript scanner](https://github.com/endikk/claudy/blob/main/Claudy/Services/TranscriptScanner.swift): `Claudy/Services/TranscriptScanner.swift`
- [Usage aggregator](https://github.com/endikk/claudy/blob/main/Claudy/Services/UsageAggregator.swift): `Claudy/Services/UsageAggregator.swift`

### Claude Code ports

- [Ports view model](https://github.com/endikk/claudy/blob/main/Claudy/ViewModels/PortsViewModel.swift): `Claudy/ViewModels/PortsViewModel.swift`
- [Port scanner](https://github.com/endikk/claudy/blob/main/Claudy/Services/PortScanner.swift): `Claudy/Services/PortScanner.swift`
- [Process table](https://github.com/endikk/claudy/blob/main/Claudy/Services/ProcessTable.swift): `Claudy/Services/ProcessTable.swift`
- [Port reaper](https://github.com/endikk/claudy/blob/main/Claudy/Services/PortReaper.swift): `Claudy/Services/PortReaper.swift`

### Views and interaction

- [Full widget view](https://github.com/endikk/claudy/blob/main/Claudy/Views/FullView.swift): `Claudy/Views/FullView.swift`
- [Menu bar view](https://github.com/endikk/claudy/blob/main/Claudy/Views/MenuBarView.swift): `Claudy/Views/MenuBarView.swift`
- [Notch view](https://github.com/endikk/claudy/blob/main/Claudy/Views/NotchView.swift): `Claudy/Views/NotchView.swift`
- [Ports view](https://github.com/endikk/claudy/blob/main/Claudy/Views/PortsView.swift): `Claudy/Views/PortsView.swift`
- [Theme and mascot](https://github.com/endikk/claudy/blob/main/Claudy/Theme/Theme.swift): `Claudy/Theme/Theme.swift`

### Other components

- **Mac user**
- **Anthropic API**

## Connections

- Mac user → App lifecycle: launches
- App lifecycle → Usage view model: creates (evidence: `Claudy/App/AppDelegate.swift`)
- App lifecycle → Placement rules: selects placement (evidence: `Claudy/App/AppDelegate.swift`)
- App lifecycle → Floating panel: shows panel (evidence: `Claudy/App/AppDelegate.swift`)
- App lifecycle → Menu bar controller: selects display (evidence: `Claudy/App/AppDelegate.swift`)
- App lifecycle → Notch controller: selects display (evidence: `Claudy/App/AppDelegate.swift`)
- App lifecycle → Update checker: starts checks (evidence: `Claudy/App/AppDelegate.swift`)
- Usage view model → Usage data source: refreshes through (evidence: `Claudy/ViewModels/UsageViewModel.swift`)
- Usage data source → Anthropic account client: loads quotas
- Anthropic account client → Anthropic API: fetches usage (evidence: `Claudy/Services/ClaudeAccountClient.swift`)
- Usage view model → OAuth sign-in: signs in (evidence: `Claudy/ViewModels/UsageViewModel.swift`)
- Account loader → Claude local data: reads account data (evidence: `Claudy/Services/AccountLoader.swift`)
- Transcript scanner → Claude local data: reads local transcripts (evidence: `Claudy/Services/TranscriptScanner.swift`)
- Usage aggregator → Transcript scanner: aggregates detail
- Usage view model → Anthropic account client: uses account client (evidence: `Claudy/ViewModels/UsageViewModel.swift`)
- Ports view model → Port scanner: scans ports (evidence: `Claudy/ViewModels/PortsViewModel.swift`)
- Ports view model → Port reaper: kills process (evidence: `Claudy/ViewModels/PortsViewModel.swift`)
- Port scanner → Process table: inspects processes (evidence: `Claudy/Services/PortScanner.swift`)
- Port reaper → Process table: checks process (evidence: `Claudy/Services/PortReaper.swift`)
- Full widget view → Usage view model: renders usage (evidence: `Claudy/Views/FullView.swift`)
- Full widget view → Ports view model: renders ports tab (evidence: `Claudy/Views/FullView.swift`)
- Menu bar view → Usage view model: renders usage (evidence: `Claudy/Views/MenuBarView.swift`)
- Notch view → Usage view model: renders usage (evidence: `Claudy/Views/NotchView.swift`)
- Ports view → Ports view model: renders port state
- Menu bar controller → Menu bar view: hosts view (evidence: `Claudy/App/MenuBarController.swift`)
- Notch controller → Notch view: hosts view (evidence: `Claudy/App/NotchController.swift`)
- Full widget view → Theme and mascot: uses styling (evidence: `Claudy/Views/FullView.swift`)
- Menu bar view → Theme and mascot: uses styling (evidence: `Claudy/Views/MenuBarView.swift`)
- Notch view → Theme and mascot: uses styling (evidence: `Claudy/Views/NotchView.swift`)
- Mac user → Usage view model: requests refresh
