# farouqaldori/claude-island architecture

> Architecture diagram of the GitHub repository farouqaldori/claude-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/farouqaldori/claude-island
- Repository: https://github.com/farouqaldori/claude-island

## Overview

Vibe Notch is a macOS menu-bar app that monitors Claude Code sessions and presents their activity in a Dynamic Island-style notch. Claude Code hooks send events over a Unix socket; the app tracks session state and parses conversation files, then displays sessions and chat history. Users can approve or reject tool requests from the notch, with tmux operations carrying those actions to the terminal. The map follows documented wiring and SOURCE INDEX references; several UI and integration details are unsampled, so uncertain links are omitted.

Main entry points: [`ClaudeIsland/UI/Views/NotchView.swift`](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/NotchView.swift) (Notch interface), [`ClaudeIsland/Services/State/SessionStore.swift`](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/State/SessionStore.swift) (Session store), [`ClaudeIsland/App/AppDelegate.swift`](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/App/AppDelegate.swift) (App lifecycle), [`ClaudeIsland/UI/Views/ChatView.swift`](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/ChatView.swift) (Chat history UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["App and Setup"]
  node_app["App lifecycle<br/>[AppDelegate.swift]"]
  node_setup["Hook setup"]
end

subgraph group_monitoring["Session Monitoring"]
  node_hook_client["Hook event sender"]
  node_socket["Hook socket"]
  node_monitor["Session monitor"]
  node_parser["Conversation parser"]
  node_watchers["Session file watchers"]
end

subgraph group_presentation["Notch Experience"]
  node_notch_vm["Notch view model"]
  node_notch_window["Notch window"]
  node_notch_ui["Notch interface<br/>[NotchView.swift]"]
  node_chat_ui["Chat history UI<br/>[ChatView.swift]"]
  node_markdown["Markdown renderer"]
  node_instances_ui["Session list"]
  node_approval_ui["Approval controls<br/>[ChatView.swift]"]
end

subgraph group_actions["Terminal Actions"]
  node_tmux["Tmux controller"]
  node_approval["Tool approval handler"]
  node_process["Process executor"]
end

subgraph group_shared["Session Data"]
  node_store["Session store<br/>[SessionStore.swift]"]
  node_session_state["Session state<br/>[SessionState.swift]"]
  node_session_phase["Session phases<br/>[SessionPhase.swift]"]
  node_chat_history["Chat history manager"]
end

node_user(("Mac user"))
node_claude["Claude Code CLI"]
node_analytics["Mixpanel"]

node_user -->|"launches"| node_app
node_app -->|"installs hooks"| node_setup
node_setup -.->|"configures hooks"| node_hook_client
node_claude -->|"emits events"| node_hook_client
node_hook_client -->|"sends events"| node_socket
node_socket -->|"delivers events"| node_monitor
node_monitor -->|"updates sessions"| node_store
node_watchers -.->|"syncs session files"| node_store
node_store -->|"loads conversation data"| node_parser
node_store -->|"maintains state"| node_session_state
node_session_state -->|"tracks lifecycle"| node_session_phase
node_user -->|"uses overlay"| node_notch_ui
node_notch_window -->|"creates model"| node_notch_vm
node_notch_ui -->|"uses view model"| node_notch_vm
node_notch_ui -->|"observes sessions"| node_monitor
node_notch_ui -->|"shows session list"| node_instances_ui
node_notch_ui -->|"shows chat"| node_chat_ui
node_chat_ui -->|"loads history"| node_chat_history
node_chat_history -->|"dispatches history events"| node_store
node_chat_history -->|"parses conversation"| node_parser
node_chat_ui -.->|"renders markdown"| node_markdown
node_user -->|"approves or rejects"| node_approval_ui
node_approval_ui -->|"dispatches approval"| node_tmux
node_tmux -->|"delegates approval"| node_approval
node_approval -->|"runs tmux commands"| node_process
node_app -.->|"records launch"| node_analytics

click node_app "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/App/AppDelegate.swift"
click node_setup "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Hooks/HookInstaller.swift"
click node_hook_client "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Resources/claude-island-state.py"
click node_socket "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Hooks/HookSocketServer.swift"
click node_monitor "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Session/ClaudeSessionMonitor.swift"
click node_parser "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Session/ConversationParser.swift"
click node_watchers "https://github.com/farouqaldori/claude-island/tree/main/ClaudeIsland/Services/Session"
click node_store "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/State/SessionStore.swift"
click node_session_state "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Models/SessionState.swift"
click node_session_phase "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Models/SessionPhase.swift"
click node_chat_history "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Chat/ChatHistoryManager.swift"
click node_notch_vm "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Core/NotchViewModel.swift"
click node_notch_window "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Window/NotchWindowController.swift"
click node_notch_ui "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/NotchView.swift"
click node_chat_ui "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/ChatView.swift"
click node_markdown "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Components/MarkdownRenderer.swift"
click node_instances_ui "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/ClaudeInstancesView.swift"
click node_approval_ui "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/ChatView.swift"
click node_tmux "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Tmux/TmuxController.swift"
click node_approval "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Tmux/ToolApprovalHandler.swift"
click node_process "https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Shared/ProcessExecutor.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_app,node_setup,node_user toneBlue
class node_hook_client,node_socket,node_monitor,node_parser,node_watchers toneAmber
class node_notch_vm,node_notch_window,node_notch_ui,node_chat_ui,node_markdown,node_instances_ui,node_approval_ui toneMint
class node_tmux,node_approval,node_process toneRose
class node_store,node_session_state,node_session_phase,node_chat_history,node_claude,node_analytics toneIndigo
```

## Components

### App and Setup

- [App lifecycle](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/App/AppDelegate.swift): `ClaudeIsland/App/AppDelegate.swift`
- [Hook setup](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Hooks/HookInstaller.swift): `ClaudeIsland/Services/Hooks/HookInstaller.swift`

### Session Monitoring

- [Hook event sender](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Resources/claude-island-state.py): `ClaudeIsland/Resources/claude-island-state.py`
- [Hook socket](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Hooks/HookSocketServer.swift): `ClaudeIsland/Services/Hooks/HookSocketServer.swift`
- [Session monitor](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Session/ClaudeSessionMonitor.swift): `ClaudeIsland/Services/Session/ClaudeSessionMonitor.swift`
- [Conversation parser](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Session/ConversationParser.swift): `ClaudeIsland/Services/Session/ConversationParser.swift`
- [Session file watchers](https://github.com/farouqaldori/claude-island/tree/main/ClaudeIsland/Services/Session): `ClaudeIsland/Services/Session`

### Notch Experience

- [Notch view model](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Core/NotchViewModel.swift): `ClaudeIsland/Core/NotchViewModel.swift`
- [Notch window](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Window/NotchWindowController.swift): `ClaudeIsland/UI/Window/NotchWindowController.swift`
- [Notch interface](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/NotchView.swift): `ClaudeIsland/UI/Views/NotchView.swift`
- [Chat history UI](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/ChatView.swift): `ClaudeIsland/UI/Views/ChatView.swift`
- [Markdown renderer](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Components/MarkdownRenderer.swift): `ClaudeIsland/UI/Components/MarkdownRenderer.swift`
- [Session list](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/ClaudeInstancesView.swift): `ClaudeIsland/UI/Views/ClaudeInstancesView.swift`
- [Approval controls](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/UI/Views/ChatView.swift): `ClaudeIsland/UI/Views/ChatView.swift`

### Terminal Actions

- [Tmux controller](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Tmux/TmuxController.swift): `ClaudeIsland/Services/Tmux/TmuxController.swift`
- [Tool approval handler](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Tmux/ToolApprovalHandler.swift): `ClaudeIsland/Services/Tmux/ToolApprovalHandler.swift`
- [Process executor](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Shared/ProcessExecutor.swift): `ClaudeIsland/Services/Shared/ProcessExecutor.swift`

### Session Data

- [Session store](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/State/SessionStore.swift): `ClaudeIsland/Services/State/SessionStore.swift`
- [Session state](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Models/SessionState.swift): `ClaudeIsland/Models/SessionState.swift`
- [Session phases](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Models/SessionPhase.swift): `ClaudeIsland/Models/SessionPhase.swift`
- [Chat history manager](https://github.com/farouqaldori/claude-island/blob/main/ClaudeIsland/Services/Chat/ChatHistoryManager.swift): `ClaudeIsland/Services/Chat/ChatHistoryManager.swift`

### Other components

- **Mac user**
- **Claude Code CLI**
- **Mixpanel**

## Connections

- Mac user → App lifecycle: launches (evidence: `README.md`)
- App lifecycle → Hook setup: installs hooks (evidence: `ClaudeIsland/App/AppDelegate.swift`)
- Hook setup → Hook event sender: configures hooks
- Claude Code CLI → Hook event sender: emits events (evidence: `README.md`)
- Hook event sender → Hook socket: sends events (evidence: `README.md`)
- Hook socket → Session monitor: delivers events (evidence: `ClaudeIsland/Services/Session/ClaudeSessionMonitor.swift`)
- Session monitor → Session store: updates sessions (evidence: `ClaudeIsland/Services/Session/ClaudeSessionMonitor.swift`)
- Session file watchers → Session store: syncs session files (evidence: `ClaudeIsland/Services/Session/ClaudeSessionMonitor.swift`)
- Session store → Conversation parser: loads conversation data (evidence: `ClaudeIsland/Services/State/SessionStore.swift`)
- Session store → Session state: maintains state (evidence: `ClaudeIsland/Services/State/SessionStore.swift`)
- Session state → Session phases: tracks lifecycle (evidence: `ClaudeIsland/Models/SessionState.swift`)
- Mac user → Notch interface: uses overlay (evidence: `README.md`)
- Notch window → Notch view model: creates model (evidence: `ClaudeIsland/UI/Window/NotchWindowController.swift`)
- Notch interface → Notch view model: uses view model (evidence: `ClaudeIsland/UI/Views/NotchView.swift`)
- Notch interface → Session monitor: observes sessions (evidence: `ClaudeIsland/UI/Views/NotchView.swift`)
- Notch interface → Session list: shows session list (evidence: `ClaudeIsland/UI/Views/NotchView.swift`)
- Notch interface → Chat history UI: shows chat (evidence: `ClaudeIsland/UI/Views/NotchView.swift`)
- Chat history UI → Chat history manager: loads history (evidence: `ClaudeIsland/UI/Views/ChatView.swift`)
- Chat history manager → Session store: dispatches history events (evidence: `ClaudeIsland/Services/Chat/ChatHistoryManager.swift`)
- Chat history manager → Conversation parser: parses conversation (evidence: `ClaudeIsland/Services/Chat/ChatHistoryManager.swift`)
- Chat history UI → Markdown renderer: renders markdown
- Mac user → Approval controls: approves or rejects (evidence: `README.md`)
- Approval controls → Tmux controller: dispatches approval (evidence: `ClaudeIsland/UI/Views/ChatView.swift`)
- Tmux controller → Tool approval handler: delegates approval (evidence: `ClaudeIsland/Services/Tmux/TmuxController.swift`)
- Tool approval handler → Process executor: runs tmux commands (evidence: `ClaudeIsland/Services/Tmux/ToolApprovalHandler.swift`)
- App lifecycle → Mixpanel: records launch