# wxtsky/codeisland architecture

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

- Interactive diagram: https://gitdiagram.com/wxtsky/codeisland
- Repository: https://github.com/wxtsky/codeisland

## Overview

CodeIsland is a macOS menu-bar/notch companion for monitoring and acting on AI coding-agent sessions, with Windows support and companion-device integrations. The main workflow is agent events into session state, then live notch cards and actions such as approvals or terminal jumps. The README documents additional capabilities represented here, including remote hosts, notifications, usage, and Buddy devices. Some subsystem links rely on README descriptions because their implementations were not sampled; the graph omits uncertain internal wiring.

Main entry points: [`Sources/CodeIsland/AppState.swift`](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/AppState.swift) (Mac app state), [`Sources/CodeIsland/NotchPanelView.swift`](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/NotchPanelView.swift) (Notch cards), [`windows/CodeIsland.Windows/App.xaml.cs`](https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Windows/App.xaml.cs) (Windows desktop app), [`Sources/CodeIsland/HookServer.swift`](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/HookServer.swift) (Hook server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Agent event intake"]
  node_bridge["Event bridge<br/>[main.swift]"]
  node_hookserver["Hook server<br/>[HookServer.swift]"]
  node_tailing["Transcript and session feeds<br/>[JSONLTailer.swift]"]
end

subgraph group_sessions["Session intelligence"]
  node_macapp["Mac app state<br/>[AppState.swift]"]
  node_snapshot["Session snapshots"]
  node_taskprogress["Task progress"]
  node_quota["Claude usage"]
  node_terminal["Terminal visibility"]
end

subgraph group_mac["Mac experience"]
  node_island["Notch cards"]
  node_panel["Panel controller"]
  node_shortcuts["Session actions"]
  node_reminders["Follow-up reminders"]
  node_settings["Settings and hooks<br/>[SettingsView.swift]"]
end

subgraph group_integrations["Remote and companion"]
  node_remote["SSH remote hosts"]
  node_push["Away notifications<br/>[PushNotifier.swift]"]
  node_buddy["Apple Buddy devices"]
  node_esp["ESP32 buddy"]
end

subgraph group_windows["Windows support"]
  node_winhooks["Windows hook manager<br/>[HookManager.cs]"]
  node_winbridge["Windows bridge<br/>[Program.cs]"]
  node_winstate["Windows session state"]
  node_winapp["Windows desktop app<br/>[App.xaml.cs]"]
end

node_user(("Developer"))
node_agents(("Coding agents"))
node_phone(("Phone and watch"))
node_espdevice(("ESP32 device"))

node_agents -.->|"send events"| node_hookserver
node_agents -.->|"write transcripts"| node_tailing
node_hookserver -.->|"forward events"| node_macapp
node_tailing -.->|"feed sessions"| node_macapp
node_macapp -->|"tracks sessions"| node_snapshot
node_macapp -->|"scans usage"| node_quota
node_macapp -->|"updates cards"| node_island
node_island -.->|"shows status"| node_user
node_user -.->|"approves or answers"| node_island
node_user -.->|"jumps to session"| node_shortcuts
node_macapp -->|"checks visibility"| node_terminal
node_reminders -->|"checks visible tab"| node_terminal
node_macapp -->|"tracks completion"| node_reminders
node_settings -.->|"configures behavior"| node_macapp
node_macapp -->|"manages hosts"| node_remote
node_macapp -->|"sends notifications"| node_push
node_macapp -->|"publishes session state"| node_buddy
node_buddy -.->|"updates companion"| node_phone
node_macapp -->|"publishes session state"| node_esp
node_esp -.->|"sends Bluetooth state"| node_espdevice
node_agents -.->|"registers hooks"| node_winhooks
node_winhooks -->|"installs bridge hook"| node_winbridge
node_winbridge -->|"applies events"| node_winstate
node_winapp -.->|"uses session state"| node_winstate
node_winapp -.->|"shows desktop status"| node_user

click node_macapp "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/AppState.swift"
click node_bridge "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandBridge/main.swift"
click node_hookserver "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/HookServer.swift"
click node_tailing "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandCore/JSONLTailer.swift"
click node_snapshot "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandCore/SessionSnapshot.swift"
click node_taskprogress "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandCore/AgentTaskParsing.swift"
click node_quota "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandCore/ClaudeQuotaClient.swift"
click node_terminal "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/TerminalVisibilityDetector.swift"
click node_island "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/NotchPanelView.swift"
click node_panel "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/PanelWindowController.swift"
click node_shortcuts "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/TerminalActivator.swift"
click node_reminders "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/FollowUpReminderController.swift"
click node_settings "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/SettingsView.swift"
click node_remote "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/RemoteManager.swift"
click node_push "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/PushNotifier.swift"
click node_buddy "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/AppleCompanionPublisher.swift"
click node_esp "https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/ESP32StatePublisher.swift"
click node_winhooks "https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Hooks/HookManager.cs"
click node_winbridge "https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Bridge/Program.cs"
click node_winstate "https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Core/SessionStateMachine.cs"
click node_winapp "https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Windows/App.xaml.cs"

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_bridge,node_hookserver,node_tailing toneBlue
class node_macapp,node_snapshot,node_taskprogress,node_quota,node_terminal toneAmber
class node_island,node_panel,node_shortcuts,node_reminders,node_settings toneMint
class node_remote,node_push,node_buddy,node_esp toneRose
class node_winhooks,node_winbridge,node_winstate,node_winapp,node_user,node_agents,node_phone,node_espdevice toneIndigo
```

## Components

### Agent event intake

- [Event bridge](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandBridge/main.swift): `Sources/CodeIslandBridge/main.swift`
- [Hook server](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/HookServer.swift): `Sources/CodeIsland/HookServer.swift`
- [Transcript and session feeds](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandCore/JSONLTailer.swift): `Sources/CodeIslandCore/JSONLTailer.swift`

### Session intelligence

- [Mac app state](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/AppState.swift): `Sources/CodeIsland/AppState.swift`
- [Session snapshots](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandCore/SessionSnapshot.swift): `Sources/CodeIslandCore/SessionSnapshot.swift`
- [Task progress](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandCore/AgentTaskParsing.swift): `Sources/CodeIslandCore/AgentTaskParsing.swift`
- [Claude usage](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIslandCore/ClaudeQuotaClient.swift): `Sources/CodeIslandCore/ClaudeQuotaClient.swift`
- [Terminal visibility](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/TerminalVisibilityDetector.swift): `Sources/CodeIsland/TerminalVisibilityDetector.swift`

### Mac experience

- [Notch cards](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/NotchPanelView.swift): `Sources/CodeIsland/NotchPanelView.swift`
- [Panel controller](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/PanelWindowController.swift): `Sources/CodeIsland/PanelWindowController.swift`
- [Session actions](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/TerminalActivator.swift): `Sources/CodeIsland/TerminalActivator.swift`
- [Follow-up reminders](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/FollowUpReminderController.swift): `Sources/CodeIsland/FollowUpReminderController.swift`
- [Settings and hooks](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/SettingsView.swift): `Sources/CodeIsland/SettingsView.swift`

### Remote and companion

- [SSH remote hosts](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/RemoteManager.swift): `Sources/CodeIsland/RemoteManager.swift`
- [Away notifications](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/PushNotifier.swift): `Sources/CodeIsland/PushNotifier.swift`
- [Apple Buddy devices](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/AppleCompanionPublisher.swift): `Sources/CodeIsland/AppleCompanionPublisher.swift`
- [ESP32 buddy](https://github.com/wxtsky/codeisland/blob/main/Sources/CodeIsland/ESP32StatePublisher.swift): `Sources/CodeIsland/ESP32StatePublisher.swift`

### Windows support

- [Windows hook manager](https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Hooks/HookManager.cs): `windows/CodeIsland.Hooks/HookManager.cs`
- [Windows bridge](https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Bridge/Program.cs): `windows/CodeIsland.Bridge/Program.cs`
- [Windows session state](https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Core/SessionStateMachine.cs): `windows/CodeIsland.Core/SessionStateMachine.cs`
- [Windows desktop app](https://github.com/wxtsky/codeisland/blob/main/windows/CodeIsland.Windows/App.xaml.cs): `windows/CodeIsland.Windows/App.xaml.cs`

### Other components

- **Developer**
- **Coding agents**
- **Phone and watch**
- **ESP32 device**

## Connections

- Coding agents → Hook server: send events (evidence: `README.md`)
- Coding agents → Transcript and session feeds: write transcripts (evidence: `README.md`)
- Hook server → Mac app state: forward events (evidence: `README.md`)
- Transcript and session feeds → Mac app state: feed sessions (evidence: `Sources/CodeIsland/AppState.swift`)
- Mac app state → Session snapshots: tracks sessions (evidence: `Sources/CodeIsland/AppState.swift`)
- Mac app state → Claude usage: scans usage (evidence: `Sources/CodeIsland/AppState.swift`)
- Mac app state → Notch cards: updates cards (evidence: `Sources/CodeIsland/AppState.swift`)
- Notch cards → Developer: shows status (evidence: `README.md`)
- Developer → Notch cards: approves or answers (evidence: `README.md`)
- Developer → Session actions: jumps to session (evidence: `README.md`)
- Mac app state → Terminal visibility: checks visibility (evidence: `Sources/CodeIsland/AppState.swift`)
- Follow-up reminders → Terminal visibility: checks visible tab (evidence: `Sources/CodeIsland/FollowUpReminderController.swift`)
- Mac app state → Follow-up reminders: tracks completion (evidence: `Sources/CodeIsland/AppState.swift`)
- Settings and hooks → Mac app state: configures behavior (evidence: `README.md`)
- Mac app state → SSH remote hosts: manages hosts (evidence: `Sources/CodeIsland/AppState.swift`)
- Mac app state → Away notifications: sends notifications (evidence: `Sources/CodeIsland/AppState.swift`)
- Mac app state → Apple Buddy devices: publishes session state (evidence: `Sources/CodeIsland/AppState.swift`)
- Apple Buddy devices → Phone and watch: updates companion (evidence: `README.md`)
- Mac app state → ESP32 buddy: publishes session state (evidence: `Sources/CodeIsland/AppState.swift`)
- ESP32 buddy → ESP32 device: sends Bluetooth state (evidence: `README.md`)
- Coding agents → Windows hook manager: registers hooks (evidence: `README.md`)
- Windows hook manager → Windows bridge: installs bridge hook (evidence: `windows/CodeIsland.Hooks/HookManager.cs`)
- Windows bridge → Windows session state: applies events (evidence: `windows/CodeIsland.Bridge/Program.cs`)
- Windows desktop app → Windows session state: uses session state
- Windows desktop app → Developer: shows desktop status (evidence: `README.md`)