How elrincondeldev/perch works
Perch turns Claude Code hook events and agent polling into persisted session state, sends updates over a token-protected WebSocket, and presents each session as an interactive creature in a macOS overlay. Users can browse the desktop session library, pin sessions, customize icons, and open sessions in Claude Desktop. The graph includes the documented optional LAN/Pi connection and focus tracking. Some module links rely on the README or SOURCE INDEX; unsampled implementation details are not inferred.
Main entry points: server.ts Hook and panel servers · StripController.swift Strip interaction · AgentLink.swift Agent WebSocket link · hub.ts Session hub
Components 25
Agent runtime
- Agent startup
agent/src/agent.ts - Hook and panel servers
agent/src/server.ts - Session state rules
agent/src/state.ts - Session hub
agent/src/hub.ts - SQLite session store
agent/src/store.ts - Claude agent poller
agent/src/poller.ts - Desktop session library
agent/src/desktop-sessions.ts - Open session
agent/src/open-session.ts - Desktop focus tracker
agent/src/desktop-focus.ts - Agent configuration
agent/src/config.ts
macOS overlay
- Overlay startup
Sources/PerchOverlay/main.swift - Agent WebSocket link
Sources/PerchOverlay/AgentLink.swift - Strip interaction
Sources/PerchOverlay/StripController.swift - Creature strip view
Sources/PerchOverlay/StripView.swift - Sprite rendering
Sources/PerchCore/Sprites/Sprite.swift - Character templates
Sources/PerchCore/Sprites/CharacterTemplate.swift - Strip layout
Sources/PerchCore/StripLayout.swift - Hover status label
Sources/PerchOverlay/HoverLabel.swift - Creature menu
Sources/PerchOverlay/CreatureMenu.swift - Menu bar controls
Sources/PerchOverlay/MenuBar.swift
Shared protocol
- Client-server contract
shared/protocol.ts
Other components
- Perch user
- Claude Code
- Claude Desktop
- Pi panel
Connections 28
- Perch user → Strip interaction: interacts with
- Claude Code → Hook and panel servers: posts hook events
- Agent startup → Hook and panel servers: starts
agent/src/agent.ts - Agent startup → Claude agent poller: starts
agent/src/agent.ts - Hook and panel servers → Session hub: handles events
agent/src/server.ts - Claude agent poller → Session hub: reconciles sessions
agent/src/poller.ts - Session hub → Session state rules: applies state rules
agent/src/hub.ts - Session hub → SQLite session store: persists state and pins
agent/src/hub.ts - Hook and panel servers → Desktop session library: lists sessions
agent/src/server.ts - Hook and panel servers → Open session: opens requested session
agent/src/server.ts - Claude Desktop → Desktop session library: provides session metadata
- Agent startup → Desktop focus tracker: tracks focus
agent/src/agent.ts - Desktop focus tracker → Session hub: updates focused session
agent/src/desktop-focus.ts - Agent configuration → Hook and panel servers: configures agent endpoints
- Hook and panel servers → Client-server contract: exchanges messages
shared/protocol.ts - Pi panel → Hook and panel servers: connects optionally
- Overlay startup → Agent WebSocket link: starts connection
Sources/PerchOverlay/main.swift - Agent WebSocket link → Hook and panel servers: exchanges WebSocket messages
- Agent WebSocket link → Client-server contract: parses and sends messages
Sources/PerchOverlay/AgentLink.swift - Agent WebSocket link → Strip interaction: supplies session updates
Sources/PerchOverlay/StripController.swift - Strip interaction → Creature strip view: renders appearances
Sources/PerchOverlay/StripController.swift - Strip interaction → Strip layout: computes layout and hits
Sources/PerchOverlay/StripController.swift - Strip interaction → Hover status label: positions status label
Sources/PerchOverlay/StripController.swift - Strip interaction → Creature menu: creates session menus
Sources/PerchOverlay/StripController.swift - Creature strip view → Sprite rendering: draws creatures
- Sprite rendering → Character templates: uses templates
Sources/PerchCore/Sprites/Sprite.swift - Menu bar controls → Agent WebSocket link: reads agent status
Sources/PerchOverlay/MenuBar.swift - Menu bar controls → Strip interaction: controls strip
Sources/PerchOverlay/MenuBar.swift