How erha19/ping-island works
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: SessionMonitor.swift Session monitor · SessionState.swift Session state · NotchViewModel.swift Island view model · DetachedIslandWindowController.swift Detached panel
Components 21
Session ingestion
- Session monitor
PingIsland/Services/Session/SessionMonitor.swift - Hook socket
PingIsland/Services/Hooks/HookSocketServer.swift - Desktop watcher
PingIsland/Services/Session/ClaudeDesktopWatcher.swift - Native runtimes
PingIsland/Services/Runtime/RuntimeCoordinator.swift - SSH connector
PingIsland/Services/Remote/RemoteConnectorManager.swift
Session state
- Session state
PingIsland/Models/SessionState.swift - Session phases
PingIsland/Models/SessionPhase.swift - Provider profiles
PingIsland/Models/SessionProvider.swift - Energy governor
PingIsland/Core/EnergyGovernor.swift
Island interface
- Island view model
PingIsland/Core/NotchViewModel.swift - Notch window
PingIsland/UI/Window/NotchWindowController.swift - Detached panel
PingIsland/UI/Window/DetachedIslandWindowController.swift - Session preview
PingIsland/UI/Views/SessionHoverPreviewView.swift - Settings window
PingIsland/UI/Window/SettingsWindowController.swift
User actions
- Tmux operations
PingIsland/Services/Tmux/TmuxController.swift - Window focus
PingIsland/Services/Window/YabaiController.swift
Supporting capabilities
- Usage summaries
PingIsland/Services/Usage/UsageSummaryPresenter.swift - Telemetry
PingIsland/Services/Analytics/TelemetryService.swift
Other components
- Mac user
- Coding agents
- SSH hosts
Connections 27
- Coding agents → Hook socket: send hooks
README.md - Coding agents → Desktop watcher: provide activity
README.md - Hook socket → Session monitor: deliver events
PingIsland/Services/Session/SessionMonitor.swift - Desktop watcher → Session monitor: report sessions
PingIsland/Services/Session/SessionMonitor.swift - Session monitor → Native runtimes: coordinate
PingIsland/Services/Session/SessionMonitor.swift - Session monitor → SSH connector: manage remote
PingIsland/Services/Session/SessionMonitor.swift - SSH hosts → SSH connector: connect via SSH
README.md - Session monitor → Energy governor: govern activity
PingIsland/Services/Session/SessionMonitor.swift - Session monitor → Telemetry: record events
PingIsland/Services/Session/SessionMonitor.swift - Session monitor → Session state: publish sessions
PingIsland/Services/Session/SessionMonitor.swift - Session state → Session phases: uses phases
PingIsland/Models/SessionState.swift - Session state → Provider profiles: uses providers
PingIsland/Models/SessionState.swift - Session monitor → Tmux operations: find targets
PingIsland/Services/Session/SessionMonitor.swift - Session monitor → Usage summaries: present usage
README.md - Session state → Island view model: informs presentation
PingIsland/Core/NotchViewModel.swift - Session monitor → Island view model: feeds UI
PingIsland/UI/Window/NotchWindowController.swift - Island view model → Notch window: drives window
PingIsland/UI/Window/NotchWindowController.swift - Session monitor → Notch window: supplies sessions
PingIsland/UI/Window/NotchWindowController.swift - Island view model → Detached panel: drives panel
PingIsland/UI/Window/DetachedIslandWindowController.swift - Session monitor → Detached panel: supplies sessions
PingIsland/UI/Window/DetachedIslandWindowController.swift - Detached panel → Session preview: renders preview
PingIsland/UI/Window/DetachedIslandWindowController.swift - Mac user → Notch window: interacts
README.md - Mac user → Detached panel: interacts
README.md - Mac user → Settings window: configures
README.md - Mac user → Tmux operations: approve or answer
README.md - Mac user → Window focus: return to app
README.md - Window focus → Tmux operations: switch pane
PingIsland/Services/Window/YabaiController.swift