# octane0411/open-vibe-island architecture

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

- Interactive diagram: https://gitdiagram.com/octane0411/open-vibe-island
- Repository: https://github.com/octane0411/open-vibe-island

## Overview

Open Island is a local-first macOS control surface for AI coding-agent sessions, with companion iPhone and Apple Watch clients. The primary flow is agent hook events → local IPC → session state → notch/top-bar overlay → user action to return to the relevant terminal or IDE. Agent-specific integrations, session discovery, hook setup, and permission/completion notifications are distinct supporting capabilities. The README documents the bridge flow; sampled excerpts confirm terminal jumping and mobile/watch event handling. Some subsystem wiring is therefore shown only where documentation supports it.

Main entry points: [`ios/OpenIslandMobile/Network/ConnectionManager.swift`](https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/Network/ConnectionManager.swift) (Mac connection), [`Sources/OpenIslandCore/BridgeServer.swift`](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/BridgeServer.swift) (Local bridge), [`ios/OpenIslandMobile/Network/WatchConnectivityManager.swift`](https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/Network/WatchConnectivityManager.swift) (Watch connectivity), [`ios/OpenIslandWatch/WatchSessionManager.swift`](https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandWatch/WatchSessionManager.swift) (Apple Watch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Agent integrations"]
  node_agent_hooks["Agent hooks<br/>[ClaudeHooks.swift]"]
  node_hook_install["Hook installation"]
  node_hooks_cli["Hooks CLI"]
end

subgraph group_runtime["Mac runtime"]
  node_bridge["Local bridge<br/>[BridgeServer.swift]"]
  node_event_model["Agent events<br/>[AgentEvent.swift]"]
  node_session_state["Session state<br/>[SessionState.swift]"]
  node_discovery["Session discovery"]
  node_app_model["App model<br/>[AppModel.swift]"]
  node_process_monitor["Process monitoring"]
end

subgraph group_surface["User surface"]
  node_overlay["Overlay controller"]
  node_panel_view["Island panel"]
  node_settings["Settings<br/>[SettingsView.swift]"]
  node_terminal_jump["Terminal jump"]
end

subgraph group_companions["Mobile companions"]
  node_mobile_app["iPhone app<br/>[App.swift]"]
  node_connection["Mac connection"]
  node_watch_link["Watch connectivity"]
  node_notifications["Notifications"]
  node_watch_app["Apple Watch"]
end

node_agent(("Coding agents"))
node_terminal(("Terminal or IDE"))
node_mac_app["macOS app"]
node_watch_user(("Watch user"))

node_agent -->|"emits hooks"| node_agent_hooks
node_settings -->|"manages hooks"| node_hook_install
node_agent_hooks -->|"invokes CLI"| node_hooks_cli
node_hooks_cli -->|"sends IPC"| node_bridge
node_bridge -->|"decodes events"| node_event_model
node_bridge -->|"updates state"| node_session_state
node_discovery -->|"discovers sessions"| node_session_state
node_process_monitor -->|"reports activity"| node_app_model
node_session_state -->|"supplies state"| node_app_model
node_mac_app -->|"starts runtime"| node_app_model
node_app_model -->|"drives overlay"| node_overlay
node_overlay -->|"hosts view"| node_panel_view
node_panel_view -->|"requests jump"| node_terminal_jump
node_terminal_jump -->|"activates target"| node_terminal
node_mobile_app -->|"starts connection"| node_connection
node_connection -->|"delivers alerts"| node_notifications
node_connection -->|"forwards events"| node_watch_link
node_watch_link -->|"sends messages"| node_watch_app
node_watch_app -->|"presents events"| node_watch_user
node_watch_user -->|"resolves request"| node_watch_app
node_watch_app -->|"returns decision"| node_watch_link
node_watch_link -->|"relays resolution"| node_connection
node_connection -.->|"connects SSE"| node_bridge

click node_agent_hooks "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/ClaudeHooks.swift"
click node_hook_install "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/HookInstallationCoordinator.swift"
click node_hooks_cli "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandHooks/OpenIslandHooksCLI.swift"
click node_bridge "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/BridgeServer.swift"
click node_event_model "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/AgentEvent.swift"
click node_session_state "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/SessionState.swift"
click node_discovery "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/SessionDiscoveryCoordinator.swift"
click node_app_model "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/AppModel.swift"
click node_process_monitor "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/ProcessMonitoringCoordinator.swift"
click node_overlay "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/OverlayPanelController.swift"
click node_panel_view "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/Views/IslandPanelView.swift"
click node_settings "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/Views/SettingsView.swift"
click node_terminal_jump "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/TerminalJumpService.swift"
click node_mac_app "https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/OpenIslandApp.swift"
click node_mobile_app "https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/App.swift"
click node_connection "https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/Network/ConnectionManager.swift"
click node_watch_link "https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/Network/WatchConnectivityManager.swift"
click node_notifications "https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/Notifications/NotificationManager.swift"
click node_watch_app "https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandWatch/WatchSessionManager.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_agent_hooks,node_hook_install,node_hooks_cli,node_watch_user toneBlue
class node_bridge,node_event_model,node_session_state,node_discovery,node_app_model,node_process_monitor toneAmber
class node_overlay,node_panel_view,node_settings,node_terminal_jump toneMint
class node_mobile_app,node_connection,node_watch_link,node_notifications,node_watch_app toneRose
class node_agent,node_terminal toneIndigo
class node_mac_app toneTeal
```

## Components

### Agent integrations

- [Agent hooks](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/ClaudeHooks.swift): `Sources/OpenIslandCore/ClaudeHooks.swift`
- [Hook installation](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/HookInstallationCoordinator.swift): `Sources/OpenIslandApp/HookInstallationCoordinator.swift`
- [Hooks CLI](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandHooks/OpenIslandHooksCLI.swift): `Sources/OpenIslandHooks/OpenIslandHooksCLI.swift`

### Mac runtime

- [Local bridge](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/BridgeServer.swift): `Sources/OpenIslandCore/BridgeServer.swift`
- [Agent events](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/AgentEvent.swift): `Sources/OpenIslandCore/AgentEvent.swift`
- [Session state](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandCore/SessionState.swift): `Sources/OpenIslandCore/SessionState.swift`
- [Session discovery](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/SessionDiscoveryCoordinator.swift): `Sources/OpenIslandApp/SessionDiscoveryCoordinator.swift`
- [App model](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/AppModel.swift): `Sources/OpenIslandApp/AppModel.swift`
- [Process monitoring](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/ProcessMonitoringCoordinator.swift): `Sources/OpenIslandApp/ProcessMonitoringCoordinator.swift`

### User surface

- [Overlay controller](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/OverlayPanelController.swift): `Sources/OpenIslandApp/OverlayPanelController.swift`
- [Island panel](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/Views/IslandPanelView.swift): `Sources/OpenIslandApp/Views/IslandPanelView.swift`
- [Settings](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/Views/SettingsView.swift): `Sources/OpenIslandApp/Views/SettingsView.swift`
- [Terminal jump](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/TerminalJumpService.swift): `Sources/OpenIslandApp/TerminalJumpService.swift`

### Mobile companions

- [iPhone app](https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/App.swift): `ios/OpenIslandMobile/App.swift`
- [Mac connection](https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/Network/ConnectionManager.swift): `ios/OpenIslandMobile/Network/ConnectionManager.swift`
- [Watch connectivity](https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/Network/WatchConnectivityManager.swift): `ios/OpenIslandMobile/Network/WatchConnectivityManager.swift`
- [Notifications](https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandMobile/Notifications/NotificationManager.swift): `ios/OpenIslandMobile/Notifications/NotificationManager.swift`
- [Apple Watch](https://github.com/octane0411/open-vibe-island/blob/main/ios/OpenIslandWatch/WatchSessionManager.swift): `ios/OpenIslandWatch/WatchSessionManager.swift`

### Other components

- **Coding agents**
- **Terminal or IDE**
- [macOS app](https://github.com/octane0411/open-vibe-island/blob/main/Sources/OpenIslandApp/OpenIslandApp.swift): `Sources/OpenIslandApp/OpenIslandApp.swift`
- **Watch user**

## Connections

- Coding agents → Agent hooks: emits hooks
- Settings → Hook installation: manages hooks
- Agent hooks → Hooks CLI: invokes CLI
- Hooks CLI → Local bridge: sends IPC
- Local bridge → Agent events: decodes events
- Local bridge → Session state: updates state
- Session discovery → Session state: discovers sessions
- Process monitoring → App model: reports activity
- Session state → App model: supplies state
- macOS app → App model: starts runtime
- App model → Overlay controller: drives overlay
- Overlay controller → Island panel: hosts view
- Island panel → Terminal jump: requests jump
- Terminal jump → Terminal or IDE: activates target
- iPhone app → Mac connection: starts connection
- Mac connection → Notifications: delivers alerts
- Mac connection → Watch connectivity: forwards events
- Watch connectivity → Apple Watch: sends messages
- Apple Watch → Watch user: presents events
- Watch user → Apple Watch: resolves request
- Apple Watch → Watch connectivity: returns decision
- Watch connectivity → Mac connection: relays resolution
- Mac connection → Local bridge: connects SSE