# yasirurf/coucou-watson architecture

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

- Interactive diagram: https://gitdiagram.com/yasirurf/coucou-watson
- Repository: https://github.com/yasirurf/coucou-watson

## Overview

Coucou is a cross-platform desktop companion for coding agents: agent hooks and optional service integrations feed live activity into a notch/top-edge island, where users can approve requests, inspect sessions, chat, and drop files. The macOS and Windows/Linux implementations have separate native and UI layers. The graph preserves documented chat, settings, character, and integration capabilities; several subsystem links are documented in the README because their implementation files were not sampled.

Main entry points: [`windows/src/island/island.ts`](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/island/island.ts) (Island UI), [`NotchBuddy/Sources/App/AppState.swift`](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/AppState.swift) (App state), [`NotchBuddy/Sources/App/IslandWindowController.swift`](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/IslandWindowController.swift) (Island window), [`windows/src/island/hooks.ts`](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/island/hooks.ts) (Hook handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mac["macOS app"]
  node_macstate["App state<br/>[AppState.swift]"]
  node_macwindow["Island window"]
  node_macview["Island views"]
  node_maccatalog["Agent pills<br/>[PillCatalog.swift]"]
  node_machooks["Agent hooks<br/>[HookServer.swift]"]
  node_macchat["Claude chat"]
  node_macupload["File drop flow"]
  node_maccontext["Window context"]
  node_macbot["Mochi character<br/>[BotEngine.swift]"]
  node_macsound["Sound engine<br/>[SoundEngine.swift]"]
end

subgraph group_web["Windows/Linux UI"]
  node_winmain["UI bootstrap<br/>[main.ts]"]
  node_winisland["Island UI<br/>[island.ts]"]
  node_winstate["UI state<br/>[state.ts]"]
  node_winlayout["Island layout<br/>[layout.ts]"]
  node_winviews["Island views<br/>[views.ts]"]
  node_winbot["Mochi renderer<br/>[engine.ts]"]
  node_winupload["Upload sequence<br/>[sequence.ts]"]
  node_winbridge["Tauri bridge<br/>[bridge.ts]"]
  node_winhooks["Hook handlers<br/>[hooks.ts]"]
  node_winintegrations["Integration handlers<br/>[integrations.ts]"]
  node_windom["DOM helpers<br/>[dom.ts]"]
end

subgraph group_native["Desktop services"]
  node_rustisland["Island window<br/>[island.rs]"]
  node_rusthooks["Hook service<br/>[hooks.rs]"]
  node_rustintegrations["Integration service<br/>[integrations.rs]"]
  node_rustclaude["Claude service<br/>[claude.rs]"]
  node_rustsettings["Settings storage<br/>[settings.rs]"]
  node_rustlog["Local logging<br/>[log.rs]"]
end

subgraph group_features["Companion features"]
  node_settings["Settings<br/>[SettingsView.swift]"]
  node_pollers["Service pollers"]
  node_sound["Sound playback<br/>[sound.ts]"]
end

node_user(("User"))
node_agent(("Coding agent"))
node_services(("External services"))

node_agent -.->|"sends hooks"| node_machooks
node_machooks -.->|"updates activity"| node_macstate
node_macstate -->|"drives island"| node_macwindow
node_macwindow -->|"hosts views"| node_macview
node_macwindow -->|"starts upload"| node_macupload
node_macwindow -->|"captures context"| node_maccontext
node_macstate -->|"uses catalog"| node_maccatalog
node_macstate -->|"uses chat service"| node_macchat
node_macstate -->|"controls sound"| node_macsound
node_user -.->|"interacts"| node_macwindow
node_user -.->|"chats"| node_macchat
node_user -.->|"drops files"| node_macupload
node_user -.->|"configures"| node_settings
node_macbot -->|"plays effects"| node_macsound
node_agent -.->|"sends hooks"| node_rusthooks
node_rusthooks -.->|"emits events"| node_winhooks
node_winmain -->|"launches"| node_winisland
node_winmain -->|"registers handlers"| node_winhooks
node_winmain -->|"registers handlers"| node_winintegrations
node_winmain -->|"boots through"| node_winbridge
node_winisland -->|"reads state"| node_winstate
node_winisland -->|"uses geometry"| node_winlayout
node_winisland -->|"builds views"| node_winviews
node_winisland -->|"renders character"| node_winbot
node_winisland -->|"runs sequence"| node_winupload
node_winisland -->|"creates elements"| node_windom
node_winhooks -->|"uses bridge"| node_winbridge
node_winhooks -->|"updates state"| node_winstate
node_winviews -->|"builds elements"| node_windom
node_winintegrations -->|"uses bridge"| node_winbridge
node_winintegrations -->|"reads state"| node_winstate
node_winbot -->|"plays sounds"| node_sound
node_winbridge -.->|"invokes commands"| node_rustisland
node_rusthooks -->|"reads settings"| node_rustsettings
node_rusthooks -->|"logs events"| node_rustlog
node_rustintegrations -->|"uses Claude service"| node_rustclaude
node_rustintegrations -->|"updates island"| node_rustisland
node_rustintegrations -->|"logs events"| node_rustlog
node_services -.->|"provides updates"| node_rustintegrations
node_settings -.->|"configures app"| node_macstate
node_user -.->|"interacts"| node_winisland
node_user -.->|"drops files"| node_winupload
node_user -.->|"approves requests"| node_winhooks
node_user -.->|"configures"| node_rustsettings

click node_macstate "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/AppState.swift"
click node_macwindow "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/IslandWindowController.swift"
click node_macview "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/IslandViewContent.swift"
click node_maccatalog "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/PillCatalog.swift"
click node_machooks "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/HookServer.swift"
click node_macchat "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/ClaudeService.swift"
click node_macupload "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/UploadSequenceEngine.swift"
click node_maccontext "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/WindowContextCapture.swift"
click node_macbot "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/BotEngine.swift"
click node_macsound "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/SoundEngine.swift"
click node_settings "https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/SettingsView.swift"
click node_pollers "https://github.com/yasirurf/coucou-watson/tree/main/NotchBuddy/Sources/App"
click node_winmain "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/main.ts"
click node_winisland "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/island/island.ts"
click node_winstate "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/core/state.ts"
click node_winlayout "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/core/layout.ts"
click node_winviews "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/views/views.ts"
click node_winbot "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/mochi/engine.ts"
click node_winupload "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/upload/sequence.ts"
click node_winbridge "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/core/bridge.ts"
click node_winhooks "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/island/hooks.ts"
click node_winintegrations "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/island/integrations.ts"
click node_windom "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/views/dom.ts"
click node_sound "https://github.com/yasirurf/coucou-watson/blob/main/windows/src/core/sound.ts"
click node_rustisland "https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/island.rs"
click node_rusthooks "https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/hooks.rs"
click node_rustintegrations "https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/integrations.rs"
click node_rustclaude "https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/claude.rs"
click node_rustsettings "https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/settings.rs"
click node_rustlog "https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/log.rs"

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_macstate,node_macwindow,node_macview,node_maccatalog,node_machooks,node_macchat,node_macupload,node_maccontext,node_macbot,node_macsound,node_user toneBlue
class node_winmain,node_winisland,node_winstate,node_winlayout,node_winviews,node_winbot,node_winupload,node_winbridge,node_winhooks,node_winintegrations,node_windom toneAmber
class node_rustisland,node_rusthooks,node_rustintegrations,node_rustclaude,node_rustsettings,node_rustlog toneMint
class node_settings,node_pollers,node_sound toneRose
class node_agent,node_services toneIndigo
```

## Components

### macOS app

- [App state](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/AppState.swift): `NotchBuddy/Sources/App/AppState.swift`
- [Island window](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/IslandWindowController.swift): `NotchBuddy/Sources/App/IslandWindowController.swift`
- [Island views](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/IslandViewContent.swift): `NotchBuddy/Sources/App/IslandViewContent.swift`
- [Agent pills](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/PillCatalog.swift): `NotchBuddy/Sources/App/PillCatalog.swift`
- [Agent hooks](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/HookServer.swift): `NotchBuddy/Sources/App/HookServer.swift`
- [Claude chat](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/ClaudeService.swift): `NotchBuddy/Sources/App/ClaudeService.swift`
- [File drop flow](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/UploadSequenceEngine.swift): `NotchBuddy/Sources/App/UploadSequenceEngine.swift`
- [Window context](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/WindowContextCapture.swift): `NotchBuddy/Sources/App/WindowContextCapture.swift`
- [Mochi character](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/BotEngine.swift): `NotchBuddy/Sources/App/BotEngine.swift`
- [Sound engine](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/SoundEngine.swift): `NotchBuddy/Sources/App/SoundEngine.swift`

### Windows/Linux UI

- [UI bootstrap](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/main.ts): `windows/src/main.ts`
- [Island UI](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/island/island.ts): `windows/src/island/island.ts`
- [UI state](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/core/state.ts): `windows/src/core/state.ts`
- [Island layout](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/core/layout.ts): `windows/src/core/layout.ts`
- [Island views](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/views/views.ts): `windows/src/views/views.ts`
- [Mochi renderer](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/mochi/engine.ts): `windows/src/mochi/engine.ts`
- [Upload sequence](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/upload/sequence.ts): `windows/src/upload/sequence.ts`
- [Tauri bridge](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/core/bridge.ts): `windows/src/core/bridge.ts`
- [Hook handlers](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/island/hooks.ts): `windows/src/island/hooks.ts`
- [Integration handlers](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/island/integrations.ts): `windows/src/island/integrations.ts`
- [DOM helpers](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/views/dom.ts): `windows/src/views/dom.ts`

### Desktop services

- [Island window](https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/island.rs): `windows/src-tauri/src/island.rs`
- [Hook service](https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/hooks.rs): `windows/src-tauri/src/hooks.rs`
- [Integration service](https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/integrations.rs): `windows/src-tauri/src/integrations.rs`
- [Claude service](https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/claude.rs): `windows/src-tauri/src/claude.rs`
- [Settings storage](https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/settings.rs): `windows/src-tauri/src/settings.rs`
- [Local logging](https://github.com/yasirurf/coucou-watson/blob/main/windows/src-tauri/src/log.rs): `windows/src-tauri/src/log.rs`

### Companion features

- [Settings](https://github.com/yasirurf/coucou-watson/blob/main/NotchBuddy/Sources/App/SettingsView.swift): `NotchBuddy/Sources/App/SettingsView.swift`
- [Service pollers](https://github.com/yasirurf/coucou-watson/tree/main/NotchBuddy/Sources/App): `NotchBuddy/Sources/App`
- [Sound playback](https://github.com/yasirurf/coucou-watson/blob/main/windows/src/core/sound.ts): `windows/src/core/sound.ts`

### Other components

- **User**
- **Coding agent**
- **External services**

## Connections

- Coding agent → Agent hooks: sends hooks
- Agent hooks → App state: updates activity
- App state → Island window: drives island (evidence: `NotchBuddy/Sources/App/IslandWindowController.swift`)
- Island window → Island views: hosts views (evidence: `NotchBuddy/Sources/App/IslandWindowController.swift`)
- Island window → File drop flow: starts upload (evidence: `NotchBuddy/Sources/App/IslandWindowController.swift`)
- Island window → Window context: captures context (evidence: `NotchBuddy/Sources/App/IslandWindowController.swift`)
- App state → Agent pills: uses catalog (evidence: `NotchBuddy/Sources/App/AppState.swift`)
- App state → Claude chat: uses chat service (evidence: `NotchBuddy/Sources/App/AppState.swift`)
- App state → Sound engine: controls sound (evidence: `NotchBuddy/Sources/App/AppState.swift`)
- User → Island window: interacts
- User → Claude chat: chats
- User → File drop flow: drops files
- User → Settings: configures
- Mochi character → Sound engine: plays effects (evidence: `NotchBuddy/Sources/App/BotEngine.swift`)
- Coding agent → Hook service: sends hooks
- Hook service → Hook handlers: emits events
- UI bootstrap → Island UI: launches (evidence: `windows/src/main.ts`)
- UI bootstrap → Hook handlers: registers handlers (evidence: `windows/src/main.ts`)
- UI bootstrap → Integration handlers: registers handlers (evidence: `windows/src/main.ts`)
- UI bootstrap → Tauri bridge: boots through (evidence: `windows/src/main.ts`)
- Island UI → UI state: reads state (evidence: `windows/src/island/island.ts`)
- Island UI → Island layout: uses geometry (evidence: `windows/src/island/island.ts`)
- Island UI → Island views: builds views (evidence: `windows/src/island/island.ts`)
- Island UI → Mochi renderer: renders character (evidence: `windows/src/island/island.ts`)
- Island UI → Upload sequence: runs sequence (evidence: `windows/src/island/island.ts`)
- Island UI → DOM helpers: creates elements (evidence: `windows/src/island/island.ts`)
- Hook handlers → Tauri bridge: uses bridge (evidence: `windows/src/island/hooks.ts`)
- Hook handlers → UI state: updates state (evidence: `windows/src/island/hooks.ts`)
- Island views → DOM helpers: builds elements (evidence: `windows/src/views/views.ts`)
- Integration handlers → Tauri bridge: uses bridge
- Integration handlers → UI state: reads state
- Mochi renderer → Sound playback: plays sounds (evidence: `windows/src/mochi/engine.ts`)
- Tauri bridge → Island window: invokes commands (evidence: `windows/src/core/bridge.ts`)
- Hook service → Settings storage: reads settings (evidence: `windows/src-tauri/src/hooks.rs`)
- Hook service → Local logging: logs events (evidence: `windows/src-tauri/src/hooks.rs`)
- Integration service → Claude service: uses Claude service (evidence: `windows/src-tauri/src/integrations.rs`)
- Integration service → Island window: updates island (evidence: `windows/src-tauri/src/integrations.rs`)
- Integration service → Local logging: logs events (evidence: `windows/src-tauri/src/integrations.rs`)
- External services → Integration service: provides updates
- Settings → App state: configures app
- User → Island UI: interacts
- User → Upload sequence: drops files
- User → Hook handlers: approves requests
- User → Settings storage: configures
