# sk-ruban/notchi architecture

> Architecture diagram of the GitHub repository sk-ruban/notchi, 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/sk-ruban/notchi
- Repository: https://github.com/sk-ruban/notchi

## Overview

Notchi is a macOS notch companion for monitoring coding-agent activity. Its primary workflow receives Claude Code and Codex hook events over a Unix socket, parses them into session state, maps activity to mascot animations, and presents those in an expandable notch panel. Other documented capabilities include prompt sentiment, usage and cost tracking, provider-specific sessions, sounds, and settings. The README supports the event-flow relationships; sampled index references support several UI/service connections. Other subsystem links are omitted where their call sites were not shown.

Main entry points: [`notchi/notchi/NotchContentView.swift`](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/NotchContentView.swift) (Notch interface), [`notchi/notchi/Views/ExpandedPanelView.swift`](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Views/ExpandedPanelView.swift) (Expanded panel), [`notchi/notchi/Core/AppSettings.swift`](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Core/AppSettings.swift) (App settings), [`notchi/notchi/Services/HookInstaller.swift`](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/HookInstaller.swift) (Agent hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_event["Agent events"]
  node_hooks["Agent hooks"]
  node_socket["Unix socket<br/>[SocketServer.swift]"]
  node_parser["Event parser"]
end

subgraph group_state["Session and analysis"]
  node_sessions[("Session store<br/>[SessionStore.swift]")]
  node_state_machine["Activity state machine"]
  node_emotion["Prompt sentiment"]
end

subgraph group_display["Notch experience"]
  node_panel_manager["Panel manager"]
  node_notch_view["Notch interface"]
  node_expanded_panel["Expanded panel"]
  node_activity_feed["Activity feed"]
  node_sprites["Session sprites"]
end

subgraph group_insights["Usage and preferences"]
  node_usage["Provider usage"]
  node_codex_usage["Codex usage"]
  node_devin_usage["Devin usage"]
  node_cost[("Cost history")]
  node_cost_dashboard["Cost dashboard"]
  node_settings[("App settings<br/>[AppSettings.swift]")]
  node_sounds["Event sounds<br/>[SoundService.swift]"]
  node_keychain[("Credential store")]
  node_updates["Auto-updates"]
end

node_claude(("Claude Code"))
node_codex(("Codex"))
node_anthropic["Anthropic API"]
node_openai["OpenAI API"]

node_claude -->|"emits events"| node_hooks
node_codex -->|"emits events"| node_hooks
node_hooks -->|"sends JSON"| node_socket
node_socket -->|"forwards events"| node_parser
node_parser -->|"maps activity"| node_state_machine
node_state_machine -->|"drives animations"| node_notch_view
node_sessions -->|"notifies count changes"| node_panel_manager
node_panel_manager -->|"controls expansion"| node_notch_view
node_notch_view -->|"reads sessions"| node_sessions
node_notch_view -->|"presents"| node_expanded_panel
node_expanded_panel -->|"reads sessions"| node_sessions
node_expanded_panel -->|"renders activity"| node_activity_feed
node_notch_view -->|"renders sprites"| node_sprites
node_emotion -.->|"analyzes prompts"| node_anthropic
node_emotion -.->|"analyzes prompts"| node_openai
node_notch_view -->|"uses usage service"| node_usage
node_notch_view -->|"uses usage service"| node_codex_usage
node_notch_view -->|"uses usage service"| node_devin_usage
node_expanded_panel -->|"reads cost history"| node_cost
node_expanded_panel -.->|"shows dashboard"| node_cost_dashboard
node_settings -->|"stores API keys"| node_keychain
node_settings -.->|"configures sounds"| node_sounds
node_expanded_panel -->|"exposes settings"| node_settings
node_expanded_panel -->|"exposes update state"| node_updates

click node_hooks "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/HookInstaller.swift"
click node_socket "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/SocketServer.swift"
click node_parser "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/ConversationParser.swift"
click node_sessions "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/SessionStore.swift"
click node_state_machine "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/NotchiStateMachine.swift"
click node_emotion "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/EmotionAnalyzer.swift"
click node_panel_manager "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/NotchPanelManager.swift"
click node_notch_view "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/NotchContentView.swift"
click node_expanded_panel "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Views/ExpandedPanelView.swift"
click node_activity_feed "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/UI/ActivityRowView.swift"
click node_sprites "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Views/SessionSpriteView.swift"
click node_usage "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/ClaudeUsageService.swift"
click node_codex_usage "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/CodexUsageService.swift"
click node_devin_usage "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/DevinUsageService.swift"
click node_cost "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/Cost/CostHistoryStore.swift"
click node_cost_dashboard "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Views/Cost/CostDashboardView.swift"
click node_settings "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Core/AppSettings.swift"
click node_sounds "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/SoundService.swift"
click node_keychain "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/KeychainManager.swift"
click node_updates "https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/Update/UpdateManager.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_hooks,node_socket,node_parser toneBlue
class node_sessions,node_state_machine,node_emotion toneAmber
class node_panel_manager,node_notch_view,node_expanded_panel,node_activity_feed,node_sprites,node_anthropic,node_openai toneMint
class node_usage,node_codex_usage,node_devin_usage,node_cost,node_cost_dashboard,node_settings,node_sounds,node_keychain,node_updates toneRose
class node_claude,node_codex toneIndigo
```

## Components

### Agent events

- [Agent hooks](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/HookInstaller.swift): `notchi/notchi/Services/HookInstaller.swift`
- [Unix socket](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/SocketServer.swift): `notchi/notchi/Services/SocketServer.swift`
- [Event parser](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/ConversationParser.swift): `notchi/notchi/Services/ConversationParser.swift`

### Session and analysis

- [Session store](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/SessionStore.swift): `notchi/notchi/Services/SessionStore.swift`
- [Activity state machine](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/NotchiStateMachine.swift): `notchi/notchi/Services/NotchiStateMachine.swift`
- [Prompt sentiment](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/EmotionAnalyzer.swift): `notchi/notchi/Services/EmotionAnalyzer.swift`

### Notch experience

- [Panel manager](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/NotchPanelManager.swift): `notchi/notchi/Services/NotchPanelManager.swift`
- [Notch interface](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/NotchContentView.swift): `notchi/notchi/NotchContentView.swift`
- [Expanded panel](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Views/ExpandedPanelView.swift): `notchi/notchi/Views/ExpandedPanelView.swift`
- [Activity feed](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/UI/ActivityRowView.swift): `notchi/notchi/UI/ActivityRowView.swift`
- [Session sprites](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Views/SessionSpriteView.swift): `notchi/notchi/Views/SessionSpriteView.swift`

### Usage and preferences

- [Provider usage](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/ClaudeUsageService.swift): `notchi/notchi/Services/ClaudeUsageService.swift`
- [Codex usage](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/CodexUsageService.swift): `notchi/notchi/Services/CodexUsageService.swift`
- [Devin usage](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/DevinUsageService.swift): `notchi/notchi/Services/DevinUsageService.swift`
- [Cost history](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/Cost/CostHistoryStore.swift): `notchi/notchi/Services/Cost/CostHistoryStore.swift`
- [Cost dashboard](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Views/Cost/CostDashboardView.swift): `notchi/notchi/Views/Cost/CostDashboardView.swift`
- [App settings](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Core/AppSettings.swift): `notchi/notchi/Core/AppSettings.swift`
- [Event sounds](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/SoundService.swift): `notchi/notchi/Services/SoundService.swift`
- [Credential store](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/KeychainManager.swift): `notchi/notchi/Services/KeychainManager.swift`
- [Auto-updates](https://github.com/sk-ruban/notchi/blob/main/notchi/notchi/Services/Update/UpdateManager.swift): `notchi/notchi/Services/Update/UpdateManager.swift`

### Other components

- **Claude Code**
- **Codex**
- **Anthropic API**
- **OpenAI API**

## Connections

- Claude Code → Agent hooks: emits events (evidence: `README.md`)
- Codex → Agent hooks: emits events (evidence: `README.md`)
- Agent hooks → Unix socket: sends JSON (evidence: `README.md`)
- Unix socket → Event parser: forwards events (evidence: `README.md`)
- Event parser → Activity state machine: maps activity (evidence: `README.md`)
- Activity state machine → Notch interface: drives animations (evidence: `README.md`)
- Session store → Panel manager: notifies count changes (evidence: `notchi/notchi/Services/NotchPanelManager.swift`)
- Panel manager → Notch interface: controls expansion (evidence: `notchi/notchi/NotchContentView.swift`)
- Notch interface → Session store: reads sessions (evidence: `notchi/notchi/NotchContentView.swift`)
- Notch interface → Expanded panel: presents (evidence: `notchi/notchi/NotchContentView.swift`)
- Expanded panel → Session store: reads sessions (evidence: `notchi/notchi/Views/ExpandedPanelView.swift`)
- Expanded panel → Activity feed: renders activity (evidence: `notchi/notchi/Views/ExpandedPanelView.swift`)
- Notch interface → Session sprites: renders sprites (evidence: `notchi/notchi/NotchContentView.swift`)
- Prompt sentiment → Anthropic API: analyzes prompts (evidence: `README.md`)
- Prompt sentiment → OpenAI API: analyzes prompts (evidence: `README.md`)
- Notch interface → Provider usage: uses usage service (evidence: `notchi/notchi/NotchContentView.swift`)
- Notch interface → Codex usage: uses usage service (evidence: `notchi/notchi/NotchContentView.swift`)
- Notch interface → Devin usage: uses usage service (evidence: `notchi/notchi/NotchContentView.swift`)
- Expanded panel → Cost history: reads cost history (evidence: `notchi/notchi/Views/ExpandedPanelView.swift`)
- Expanded panel → Cost dashboard: shows dashboard (evidence: `README.md`)
- App settings → Credential store: stores API keys (evidence: `notchi/notchi/Core/AppSettings.swift`)
- App settings → Event sounds: configures sounds (evidence: `notchi/notchi/Core/AppSettings.swift`)
- Expanded panel → App settings: exposes settings (evidence: `notchi/notchi/Views/ExpandedPanelView.swift`)
- Expanded panel → Auto-updates: exposes update state (evidence: `notchi/notchi/Views/ExpandedPanelView.swift`)
