How wxtsky/codeisland works
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: AppState.swift Mac app state · NotchPanelView.swift Notch cards · App.xaml.cs Windows desktop app · HookServer.swift Hook server
Components 25
Agent event intake
- Event bridge
Sources/CodeIslandBridge/main.swift - Hook server
Sources/CodeIsland/HookServer.swift - Transcript and session feeds
Sources/CodeIslandCore/JSONLTailer.swift
Session intelligence
- Mac app state
Sources/CodeIsland/AppState.swift - Session snapshots
Sources/CodeIslandCore/SessionSnapshot.swift - Task progress
Sources/CodeIslandCore/AgentTaskParsing.swift - Claude usage
Sources/CodeIslandCore/ClaudeQuotaClient.swift - Terminal visibility
Sources/CodeIsland/TerminalVisibilityDetector.swift
Mac experience
- Notch cards
Sources/CodeIsland/NotchPanelView.swift - Panel controller
Sources/CodeIsland/PanelWindowController.swift - Session actions
Sources/CodeIsland/TerminalActivator.swift - Follow-up reminders
Sources/CodeIsland/FollowUpReminderController.swift - Settings and hooks
Sources/CodeIsland/SettingsView.swift
Remote and companion
- SSH remote hosts
Sources/CodeIsland/RemoteManager.swift - Away notifications
Sources/CodeIsland/PushNotifier.swift - Apple Buddy devices
Sources/CodeIsland/AppleCompanionPublisher.swift - ESP32 buddy
Sources/CodeIsland/ESP32StatePublisher.swift
Windows support
- Windows hook manager
windows/CodeIsland.Hooks/HookManager.cs - Windows bridge
windows/CodeIsland.Bridge/Program.cs - Windows session state
windows/CodeIsland.Core/SessionStateMachine.cs - Windows desktop app
windows/CodeIsland.Windows/App.xaml.cs
Other components
- Developer
- Coding agents
- Phone and watch
- ESP32 device
Connections 25
- Coding agents → Hook server: send events
README.md - Coding agents → Transcript and session feeds: write transcripts
README.md - Hook server → Mac app state: forward events
README.md - Transcript and session feeds → Mac app state: feed sessions
Sources/CodeIsland/AppState.swift - Mac app state → Session snapshots: tracks sessions
Sources/CodeIsland/AppState.swift - Mac app state → Claude usage: scans usage
Sources/CodeIsland/AppState.swift - Mac app state → Notch cards: updates cards
Sources/CodeIsland/AppState.swift - Notch cards → Developer: shows status
README.md - Developer → Notch cards: approves or answers
README.md - Developer → Session actions: jumps to session
README.md - Mac app state → Terminal visibility: checks visibility
Sources/CodeIsland/AppState.swift - Follow-up reminders → Terminal visibility: checks visible tab
Sources/CodeIsland/FollowUpReminderController.swift - Mac app state → Follow-up reminders: tracks completion
Sources/CodeIsland/AppState.swift - Settings and hooks → Mac app state: configures behavior
README.md - Mac app state → SSH remote hosts: manages hosts
Sources/CodeIsland/AppState.swift - Mac app state → Away notifications: sends notifications
Sources/CodeIsland/AppState.swift - Mac app state → Apple Buddy devices: publishes session state
Sources/CodeIsland/AppState.swift - Apple Buddy devices → Phone and watch: updates companion
README.md - Mac app state → ESP32 buddy: publishes session state
Sources/CodeIsland/AppState.swift - ESP32 buddy → ESP32 device: sends Bluetooth state
README.md - Coding agents → Windows hook manager: registers hooks
README.md - Windows hook manager → Windows bridge: installs bridge hook
windows/CodeIsland.Hooks/HookManager.cs - Windows bridge → Windows session state: applies events
windows/CodeIsland.Bridge/Program.cs - Windows desktop app → Windows session state: uses session state
- Windows desktop app → Developer: shows desktop status
README.md