How sk-ruban/notchi works
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: NotchContentView.swift Notch interface · ExpandedPanelView.swift Expanded panel · AppSettings.swift App settings · HookInstaller.swift Agent hooks
Components 24
Agent events
- Agent hooks
notchi/notchi/Services/HookInstaller.swift - Unix socket
notchi/notchi/Services/SocketServer.swift - Event parser
notchi/notchi/Services/ConversationParser.swift
Session and analysis
- Session store
notchi/notchi/Services/SessionStore.swift - Activity state machine
notchi/notchi/Services/NotchiStateMachine.swift - Prompt sentiment
notchi/notchi/Services/EmotionAnalyzer.swift
Notch experience
- Panel manager
notchi/notchi/Services/NotchPanelManager.swift - Notch interface
notchi/notchi/NotchContentView.swift - Expanded panel
notchi/notchi/Views/ExpandedPanelView.swift - Activity feed
notchi/notchi/UI/ActivityRowView.swift - Session sprites
notchi/notchi/Views/SessionSpriteView.swift
Usage and preferences
- Provider usage
notchi/notchi/Services/ClaudeUsageService.swift - Codex usage
notchi/notchi/Services/CodexUsageService.swift - Devin usage
notchi/notchi/Services/DevinUsageService.swift - Cost history
notchi/notchi/Services/Cost/CostHistoryStore.swift - Cost dashboard
notchi/notchi/Views/Cost/CostDashboardView.swift - App settings
notchi/notchi/Core/AppSettings.swift - Event sounds
notchi/notchi/Services/SoundService.swift - Credential store
notchi/notchi/Services/KeychainManager.swift - Auto-updates
notchi/notchi/Services/Update/UpdateManager.swift
Other components
- Claude Code
- Codex
- Anthropic API
- OpenAI API
Connections 24
- Claude Code → Agent hooks: emits events
README.md - Codex → Agent hooks: emits events
README.md - Agent hooks → Unix socket: sends JSON
README.md - Unix socket → Event parser: forwards events
README.md - Event parser → Activity state machine: maps activity
README.md - Activity state machine → Notch interface: drives animations
README.md - Session store → Panel manager: notifies count changes
notchi/notchi/Services/NotchPanelManager.swift - Panel manager → Notch interface: controls expansion
notchi/notchi/NotchContentView.swift - Notch interface → Session store: reads sessions
notchi/notchi/NotchContentView.swift - Notch interface → Expanded panel: presents
notchi/notchi/NotchContentView.swift - Expanded panel → Session store: reads sessions
notchi/notchi/Views/ExpandedPanelView.swift - Expanded panel → Activity feed: renders activity
notchi/notchi/Views/ExpandedPanelView.swift - Notch interface → Session sprites: renders sprites
notchi/notchi/NotchContentView.swift - Prompt sentiment → Anthropic API: analyzes prompts
README.md - Prompt sentiment → OpenAI API: analyzes prompts
README.md - Notch interface → Provider usage: uses usage service
notchi/notchi/NotchContentView.swift - Notch interface → Codex usage: uses usage service
notchi/notchi/NotchContentView.swift - Notch interface → Devin usage: uses usage service
notchi/notchi/NotchContentView.swift - Expanded panel → Cost history: reads cost history
notchi/notchi/Views/ExpandedPanelView.swift - Expanded panel → Cost dashboard: shows dashboard
README.md - App settings → Credential store: stores API keys
notchi/notchi/Core/AppSettings.swift - App settings → Event sounds: configures sounds
notchi/notchi/Core/AppSettings.swift - Expanded panel → App settings: exposes settings
notchi/notchi/Views/ExpandedPanelView.swift - Expanded panel → Auto-updates: exposes update state
notchi/notchi/Views/ExpandedPanelView.swift