# louis-cfm/coucou architecture

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

- Interactive diagram: https://gitdiagram.com/louis-cfm/coucou
- Repository: https://github.com/louis-cfm/coucou

## Overview

Coucou is a cross-platform notch/top-edge companion for Claude Code: session activity and approval events reach the island, where users can inspect work, approve or deny requests, chat, and handle files. The macOS implementation is native SwiftUI/AppKit; Windows pairs a Tauri/Rust backend with a TypeScript island. Both also display optional service integrations and animate Mochi. Some subsystem links below are documented in the README; unsampled implementation details are not inferred.

Main entry points: [`windows/src/island/island.ts`](https://github.com/louis-cfm/coucou/blob/main/windows/src/island/island.ts) (Island interaction and layout), [`windows/src-tauri/src/lib.rs`](https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/lib.rs) (Tauri app commands), [`NotchBuddy/Sources/App/IslandWindowController.swift`](https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/IslandWindowController.swift) (Island window and views), [`windows/src/main.ts`](https://github.com/louis-cfm/coucou/blob/main/windows/src/main.ts) (Frontend startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mac["macOS app"]
  node_mac_app["App lifecycle and state<br/>[AppState.swift]"]
  node_mac_island["Island window and views"]
  node_mac_hook["Hook event server<br/>[HookServer.swift]"]
  node_mac_claude["Claude chat service"]
  node_mac_integrations["Integration polling"]
  node_mac_character["Mochi animation and sound<br/>[BotEngine.swift]"]
  node_mac_upload["File drop sequence"]
  node_mac_context["Window context capture"]
end

subgraph group_winui["Windows island UI"]
  node_win_entry["Frontend startup<br/>[main.ts]"]
  node_win_island["Island interaction and layout<br/>[island.ts]"]
  node_win_views["Island views<br/>[views.ts]"]
  node_win_mochi["Mochi animation<br/>[engine.ts]"]
  node_win_upload["Upload sequence<br/>[sequence.ts]"]
  node_win_state["Frontend app state<br/>[state.ts]"]
  node_win_bridge["Tauri bridge<br/>[bridge.ts]"]
  node_win_hooks["Hook event handling<br/>[hooks.ts]"]
  node_win_integrations_ui["Integration event handling<br/>[integrations.ts]"]
end

subgraph group_winbackend["Windows services"]
  node_win_backend["Tauri app commands<br/>[lib.rs]"]
  node_win_pipe["Named-pipe hook transport<br/>[pipe.rs]"]
  node_win_claude["Claude API service<br/>[claude.rs]"]
  node_win_integrations["Integration polling<br/>[integrations.rs]"]
  node_win_settings["Settings and secrets<br/>[settings.rs]"]
end

subgraph group_sharedfeatures["Companion features"]
end

node_user(("User"))
node_claude["Claude Code"]
node_external_services["Connected services"]

node_claude -->|"sends hook events"| node_mac_hook
node_mac_hook -->|"forwards events"| node_mac_island
node_user -->|"interacts with"| node_mac_island
node_user -->|"drops files"| node_mac_upload
node_user -->|"attaches window"| node_mac_context
node_user -->|"asks questions"| node_mac_claude
node_external_services -.->|"provides updates"| node_mac_integrations
node_mac_island -.->|"renders character"| node_mac_character
node_mac_island -.->|"shows updates"| node_mac_integrations
node_user -->|"interacts with"| node_win_island
node_claude -->|"sends hook events"| node_win_pipe
node_win_pipe -.->|"relays events"| node_win_backend
node_win_entry -->|"launches"| node_win_island
node_win_entry -->|"registers handlers"| node_win_hooks
node_win_entry -->|"registers handlers"| node_win_integrations_ui
node_win_island -->|"builds views"| node_win_views
node_win_island -->|"ticks animation"| node_win_mochi
node_win_island -->|"steps sequence"| node_win_upload
node_win_island -->|"reads state"| node_win_state
node_win_bridge -->|"invokes commands"| node_win_backend
node_win_hooks -->|"uses bridge"| node_win_bridge
node_win_integrations_ui -->|"uses bridge"| node_win_bridge
node_win_backend -->|"dispatches commands"| node_win_claude
node_win_backend -->|"dispatches commands"| node_win_integrations
node_win_backend -->|"loads settings"| node_win_settings
node_external_services -.->|"provides updates"| node_win_integrations
node_user -.->|"chats with Claude"| node_win_claude
node_user -.->|"drops files"| node_win_upload

click node_mac_app "https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/AppState.swift"
click node_mac_island "https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/IslandWindowController.swift"
click node_mac_hook "https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/HookServer.swift"
click node_mac_claude "https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/ClaudeService.swift"
click node_mac_integrations "https://github.com/louis-cfm/coucou/tree/main/NotchBuddy/Sources/App"
click node_mac_character "https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/BotEngine.swift"
click node_mac_upload "https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/UploadSequenceEngine.swift"
click node_mac_context "https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/WindowContextCapture.swift"
click node_win_entry "https://github.com/louis-cfm/coucou/blob/main/windows/src/main.ts"
click node_win_island "https://github.com/louis-cfm/coucou/blob/main/windows/src/island/island.ts"
click node_win_views "https://github.com/louis-cfm/coucou/blob/main/windows/src/views/views.ts"
click node_win_mochi "https://github.com/louis-cfm/coucou/blob/main/windows/src/mochi/engine.ts"
click node_win_upload "https://github.com/louis-cfm/coucou/blob/main/windows/src/upload/sequence.ts"
click node_win_state "https://github.com/louis-cfm/coucou/blob/main/windows/src/core/state.ts"
click node_win_bridge "https://github.com/louis-cfm/coucou/blob/main/windows/src/core/bridge.ts"
click node_win_hooks "https://github.com/louis-cfm/coucou/blob/main/windows/src/island/hooks.ts"
click node_win_integrations_ui "https://github.com/louis-cfm/coucou/blob/main/windows/src/island/integrations.ts"
click node_win_backend "https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/lib.rs"
click node_win_pipe "https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/pipe.rs"
click node_win_claude "https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/claude.rs"
click node_win_integrations "https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/integrations.rs"
click node_win_settings "https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/settings.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_mac_app,node_mac_island,node_mac_hook,node_mac_claude,node_mac_integrations,node_mac_character,node_mac_upload,node_mac_context,node_user toneBlue
class node_win_entry,node_win_island,node_win_views,node_win_mochi,node_win_upload,node_win_state,node_win_bridge,node_win_hooks,node_win_integrations_ui toneAmber
class node_win_backend,node_win_pipe,node_win_claude,node_win_integrations,node_win_settings toneMint
class node_claude,node_external_services toneIndigo
```

## Components

### macOS app

- [App lifecycle and state](https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/AppState.swift): `NotchBuddy/Sources/App/AppState.swift`
- [Island window and views](https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/IslandWindowController.swift): `NotchBuddy/Sources/App/IslandWindowController.swift`
- [Hook event server](https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/HookServer.swift): `NotchBuddy/Sources/App/HookServer.swift`
- [Claude chat service](https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/ClaudeService.swift): `NotchBuddy/Sources/App/ClaudeService.swift`
- [Integration polling](https://github.com/louis-cfm/coucou/tree/main/NotchBuddy/Sources/App): `NotchBuddy/Sources/App`
- [Mochi animation and sound](https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/BotEngine.swift): `NotchBuddy/Sources/App/BotEngine.swift`
- [File drop sequence](https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/UploadSequenceEngine.swift): `NotchBuddy/Sources/App/UploadSequenceEngine.swift`
- [Window context capture](https://github.com/louis-cfm/coucou/blob/main/NotchBuddy/Sources/App/WindowContextCapture.swift): `NotchBuddy/Sources/App/WindowContextCapture.swift`

### Windows island UI

- [Frontend startup](https://github.com/louis-cfm/coucou/blob/main/windows/src/main.ts): `windows/src/main.ts`
- [Island interaction and layout](https://github.com/louis-cfm/coucou/blob/main/windows/src/island/island.ts): `windows/src/island/island.ts`
- [Island views](https://github.com/louis-cfm/coucou/blob/main/windows/src/views/views.ts): `windows/src/views/views.ts`
- [Mochi animation](https://github.com/louis-cfm/coucou/blob/main/windows/src/mochi/engine.ts): `windows/src/mochi/engine.ts`
- [Upload sequence](https://github.com/louis-cfm/coucou/blob/main/windows/src/upload/sequence.ts): `windows/src/upload/sequence.ts`
- [Frontend app state](https://github.com/louis-cfm/coucou/blob/main/windows/src/core/state.ts): `windows/src/core/state.ts`
- [Tauri bridge](https://github.com/louis-cfm/coucou/blob/main/windows/src/core/bridge.ts): `windows/src/core/bridge.ts`
- [Hook event handling](https://github.com/louis-cfm/coucou/blob/main/windows/src/island/hooks.ts): `windows/src/island/hooks.ts`
- [Integration event handling](https://github.com/louis-cfm/coucou/blob/main/windows/src/island/integrations.ts): `windows/src/island/integrations.ts`

### Windows services

- [Tauri app commands](https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/lib.rs): `windows/src-tauri/src/lib.rs`
- [Named-pipe hook transport](https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/pipe.rs): `windows/src-tauri/src/pipe.rs`
- [Claude API service](https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/claude.rs): `windows/src-tauri/src/claude.rs`
- [Integration polling](https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/integrations.rs): `windows/src-tauri/src/integrations.rs`
- [Settings and secrets](https://github.com/louis-cfm/coucou/blob/main/windows/src-tauri/src/settings.rs): `windows/src-tauri/src/settings.rs`

### Other components

- **User**
- **Claude Code**
- **Connected services**

## Connections

- Claude Code → Hook event server: sends hook events (evidence: `README.md`)
- Hook event server → Island window and views: forwards events (evidence: `README.md`)
- User → Island window and views: interacts with (evidence: `README.md`)
- User → File drop sequence: drops files (evidence: `README.md`)
- User → Window context capture: attaches window (evidence: `README.md`)
- User → Claude chat service: asks questions (evidence: `README.md`)
- Connected services → Integration polling: provides updates (evidence: `README.md`)
- Island window and views → Mochi animation and sound: renders character (evidence: `README.md`)
- Island window and views → Integration polling: shows updates (evidence: `README.md`)
- User → Island interaction and layout: interacts with (evidence: `README.md`)
- Claude Code → Named-pipe hook transport: sends hook events (evidence: `README.md`)
- Named-pipe hook transport → Tauri app commands: relays events (evidence: `windows/src-tauri/src/lib.rs`)
- Frontend startup → Island interaction and layout: launches (evidence: `windows/src/main.ts`)
- Frontend startup → Hook event handling: registers handlers (evidence: `windows/src/main.ts`)
- Frontend startup → Integration event handling: registers handlers (evidence: `windows/src/main.ts`)
- Island interaction and layout → Island views: builds views (evidence: `windows/src/island/island.ts`)
- Island interaction and layout → Mochi animation: ticks animation (evidence: `windows/src/island/island.ts`)
- Island interaction and layout → Upload sequence: steps sequence (evidence: `windows/src/island/island.ts`)
- Island interaction and layout → Frontend app state: reads state (evidence: `windows/src/island/island.ts`)
- Tauri bridge → Tauri app commands: invokes commands (evidence: `windows/src/core/bridge.ts`)
- Hook event handling → Tauri bridge: uses bridge (evidence: `windows/src/island/hooks.ts`)
- Integration event handling → Tauri bridge: uses bridge
- Tauri app commands → Claude API service: dispatches commands (evidence: `windows/src-tauri/src/lib.rs`)
- Tauri app commands → Integration polling: dispatches commands (evidence: `windows/src-tauri/src/lib.rs`)
- Tauri app commands → Settings and secrets: loads settings (evidence: `windows/src-tauri/src/lib.rs`)
- Connected services → Integration polling: provides updates (evidence: `README.md`)
- User → Claude API service: chats with Claude (evidence: `README.md`)
- User → Upload sequence: drops files (evidence: `README.md`)
