# erha19/ping-island architecture

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

- Interactive diagram: https://gitdiagram.com/erha19/ping-island
- Repository: https://github.com/erha19/ping-island

## Overview

Ping Island is a macOS menu-bar monitor for AI coding sessions. Agent hooks, transcripts, app-server events, and remote activity feed session state; the app surfaces attention in a notch or detached panel, where users can answer prompts, handle tool approvals, and return to the right terminal or IDE. The README also documents usage summaries, settings, and SSH support. The graph combines those documented capabilities with relationships visible in the supplied source excerpts and index; unsampled implementation links are omitted.

Main entry points: [`PingIsland/Services/Session/SessionMonitor.swift`](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Session/SessionMonitor.swift) (Session monitor), [`PingIsland/Models/SessionState.swift`](https://github.com/erha19/ping-island/blob/main/PingIsland/Models/SessionState.swift) (Session state), [`PingIsland/Core/NotchViewModel.swift`](https://github.com/erha19/ping-island/blob/main/PingIsland/Core/NotchViewModel.swift) (Island view model), [`PingIsland/UI/Window/DetachedIslandWindowController.swift`](https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Window/DetachedIslandWindowController.swift) (Detached panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Session ingestion"]
  node_session_monitor["Session monitor"]
  node_hook_server["Hook socket"]
  node_desktop_watcher["Desktop watcher"]
  node_runtime["Native runtimes"]
  node_remote["SSH connector"]
end

subgraph group_state["Session state"]
  node_session_state["Session state<br/>[SessionState.swift]"]
  node_session_phase["Session phases<br/>[SessionPhase.swift]"]
  node_session_provider["Provider profiles"]
  node_energy["Energy governor"]
end

subgraph group_surface["Island interface"]
  node_viewmodel["Island view model"]
  node_notch_window["Notch window"]
  node_detached["Detached panel"]
  node_hover_preview["Session preview"]
  node_settings["Settings window"]
end

subgraph group_actions["User actions"]
  node_tmux["Tmux operations"]
  node_window_focus["Window focus"]
end

subgraph group_support["Supporting capabilities"]
  node_usage["Usage summaries"]
  node_telemetry["Telemetry"]
end

node_user(("Mac user"))
node_agents{{"Coding agents"}}
node_ssh{{"SSH hosts"}}

node_agents -.->|"send hooks"| node_hook_server
node_agents -.->|"provide activity"| node_desktop_watcher
node_hook_server -.->|"deliver events"| node_session_monitor
node_desktop_watcher -.->|"report sessions"| node_session_monitor
node_session_monitor -->|"coordinate"| node_runtime
node_session_monitor -->|"manage remote"| node_remote
node_ssh -.->|"connect via SSH"| node_remote
node_session_monitor -->|"govern activity"| node_energy
node_session_monitor -->|"record events"| node_telemetry
node_session_monitor -->|"publish sessions"| node_session_state
node_session_state -->|"uses phases"| node_session_phase
node_session_state -->|"uses providers"| node_session_provider
node_session_monitor -->|"find targets"| node_tmux
node_session_monitor -.->|"present usage"| node_usage
node_session_state -.->|"informs presentation"| node_viewmodel
node_session_monitor -->|"feeds UI"| node_viewmodel
node_viewmodel -->|"drives window"| node_notch_window
node_session_monitor -->|"supplies sessions"| node_notch_window
node_viewmodel -->|"drives panel"| node_detached
node_session_monitor -->|"supplies sessions"| node_detached
node_detached -.->|"renders preview"| node_hover_preview
node_user -.->|"interacts"| node_notch_window
node_user -.->|"interacts"| node_detached
node_user -.->|"configures"| node_settings
node_user -.->|"approve or answer"| node_tmux
node_user -.->|"return to app"| node_window_focus
node_window_focus -->|"switch pane"| node_tmux

click node_session_monitor "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Session/SessionMonitor.swift"
click node_hook_server "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Hooks/HookSocketServer.swift"
click node_desktop_watcher "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Session/ClaudeDesktopWatcher.swift"
click node_runtime "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Runtime/RuntimeCoordinator.swift"
click node_remote "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Remote/RemoteConnectorManager.swift"
click node_session_state "https://github.com/erha19/ping-island/blob/main/PingIsland/Models/SessionState.swift"
click node_session_phase "https://github.com/erha19/ping-island/blob/main/PingIsland/Models/SessionPhase.swift"
click node_session_provider "https://github.com/erha19/ping-island/blob/main/PingIsland/Models/SessionProvider.swift"
click node_energy "https://github.com/erha19/ping-island/blob/main/PingIsland/Core/EnergyGovernor.swift"
click node_viewmodel "https://github.com/erha19/ping-island/blob/main/PingIsland/Core/NotchViewModel.swift"
click node_notch_window "https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Window/NotchWindowController.swift"
click node_detached "https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Window/DetachedIslandWindowController.swift"
click node_hover_preview "https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Views/SessionHoverPreviewView.swift"
click node_settings "https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Window/SettingsWindowController.swift"
click node_tmux "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Tmux/TmuxController.swift"
click node_window_focus "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Window/YabaiController.swift"
click node_usage "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Usage/UsageSummaryPresenter.swift"
click node_telemetry "https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Analytics/TelemetryService.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_session_monitor,node_hook_server,node_desktop_watcher,node_runtime,node_remote,node_user toneBlue
class node_session_state,node_session_phase,node_session_provider,node_energy toneAmber
class node_viewmodel,node_notch_window,node_detached,node_hover_preview,node_settings toneMint
class node_tmux,node_window_focus toneRose
class node_usage,node_telemetry,node_agents,node_ssh toneIndigo
```

## Components

### Session ingestion

- [Session monitor](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Session/SessionMonitor.swift): `PingIsland/Services/Session/SessionMonitor.swift`
- [Hook socket](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Hooks/HookSocketServer.swift): `PingIsland/Services/Hooks/HookSocketServer.swift`
- [Desktop watcher](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Session/ClaudeDesktopWatcher.swift): `PingIsland/Services/Session/ClaudeDesktopWatcher.swift`
- [Native runtimes](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Runtime/RuntimeCoordinator.swift): `PingIsland/Services/Runtime/RuntimeCoordinator.swift`
- [SSH connector](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Remote/RemoteConnectorManager.swift): `PingIsland/Services/Remote/RemoteConnectorManager.swift`

### Session state

- [Session state](https://github.com/erha19/ping-island/blob/main/PingIsland/Models/SessionState.swift): `PingIsland/Models/SessionState.swift`
- [Session phases](https://github.com/erha19/ping-island/blob/main/PingIsland/Models/SessionPhase.swift): `PingIsland/Models/SessionPhase.swift`
- [Provider profiles](https://github.com/erha19/ping-island/blob/main/PingIsland/Models/SessionProvider.swift): `PingIsland/Models/SessionProvider.swift`
- [Energy governor](https://github.com/erha19/ping-island/blob/main/PingIsland/Core/EnergyGovernor.swift): `PingIsland/Core/EnergyGovernor.swift`

### Island interface

- [Island view model](https://github.com/erha19/ping-island/blob/main/PingIsland/Core/NotchViewModel.swift): `PingIsland/Core/NotchViewModel.swift`
- [Notch window](https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Window/NotchWindowController.swift): `PingIsland/UI/Window/NotchWindowController.swift`
- [Detached panel](https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Window/DetachedIslandWindowController.swift): `PingIsland/UI/Window/DetachedIslandWindowController.swift`
- [Session preview](https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Views/SessionHoverPreviewView.swift): `PingIsland/UI/Views/SessionHoverPreviewView.swift`
- [Settings window](https://github.com/erha19/ping-island/blob/main/PingIsland/UI/Window/SettingsWindowController.swift): `PingIsland/UI/Window/SettingsWindowController.swift`

### User actions

- [Tmux operations](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Tmux/TmuxController.swift): `PingIsland/Services/Tmux/TmuxController.swift`
- [Window focus](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Window/YabaiController.swift): `PingIsland/Services/Window/YabaiController.swift`

### Supporting capabilities

- [Usage summaries](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Usage/UsageSummaryPresenter.swift): `PingIsland/Services/Usage/UsageSummaryPresenter.swift`
- [Telemetry](https://github.com/erha19/ping-island/blob/main/PingIsland/Services/Analytics/TelemetryService.swift): `PingIsland/Services/Analytics/TelemetryService.swift`

### Other components

- **Mac user**
- **Coding agents**
- **SSH hosts**

## Connections

- Coding agents → Hook socket: send hooks (evidence: `README.md`)
- Coding agents → Desktop watcher: provide activity (evidence: `README.md`)
- Hook socket → Session monitor: deliver events (evidence: `PingIsland/Services/Session/SessionMonitor.swift`)
- Desktop watcher → Session monitor: report sessions (evidence: `PingIsland/Services/Session/SessionMonitor.swift`)
- Session monitor → Native runtimes: coordinate (evidence: `PingIsland/Services/Session/SessionMonitor.swift`)
- Session monitor → SSH connector: manage remote (evidence: `PingIsland/Services/Session/SessionMonitor.swift`)
- SSH hosts → SSH connector: connect via SSH (evidence: `README.md`)
- Session monitor → Energy governor: govern activity (evidence: `PingIsland/Services/Session/SessionMonitor.swift`)
- Session monitor → Telemetry: record events (evidence: `PingIsland/Services/Session/SessionMonitor.swift`)
- Session monitor → Session state: publish sessions (evidence: `PingIsland/Services/Session/SessionMonitor.swift`)
- Session state → Session phases: uses phases (evidence: `PingIsland/Models/SessionState.swift`)
- Session state → Provider profiles: uses providers (evidence: `PingIsland/Models/SessionState.swift`)
- Session monitor → Tmux operations: find targets (evidence: `PingIsland/Services/Session/SessionMonitor.swift`)
- Session monitor → Usage summaries: present usage (evidence: `README.md`)
- Session state → Island view model: informs presentation (evidence: `PingIsland/Core/NotchViewModel.swift`)
- Session monitor → Island view model: feeds UI (evidence: `PingIsland/UI/Window/NotchWindowController.swift`)
- Island view model → Notch window: drives window (evidence: `PingIsland/UI/Window/NotchWindowController.swift`)
- Session monitor → Notch window: supplies sessions (evidence: `PingIsland/UI/Window/NotchWindowController.swift`)
- Island view model → Detached panel: drives panel (evidence: `PingIsland/UI/Window/DetachedIslandWindowController.swift`)
- Session monitor → Detached panel: supplies sessions (evidence: `PingIsland/UI/Window/DetachedIslandWindowController.swift`)
- Detached panel → Session preview: renders preview (evidence: `PingIsland/UI/Window/DetachedIslandWindowController.swift`)
- Mac user → Notch window: interacts (evidence: `README.md`)
- Mac user → Detached panel: interacts (evidence: `README.md`)
- Mac user → Settings window: configures (evidence: `README.md`)
- Mac user → Tmux operations: approve or answer (evidence: `README.md`)
- Mac user → Window focus: return to app (evidence: `README.md`)
- Window focus → Tmux operations: switch pane (evidence: `PingIsland/Services/Window/YabaiController.swift`)