How steipete/peekaboo works
Peekaboo is a macOS automation product with a CLI and menu-bar app. Its core workflow is to observe the screen or accessibility tree, select a target, and perform a native UI action; agent sessions can plan and execute multi-step work using those tools. MCP exposes tools to external clients, while capture, macOS control, configuration, and permissions are additional capabilities. The graph follows documented product relationships and sampled source entry points; unsampled subsystem wiring is represented only where README documentation supports it.
Main entry points: CommanderRuntimeRouter.swift Command Router · SeeCommand.swift Screen Observation · PeekabooAgentService+SessionLifecycle.swift Agent Sessions · MCPCommand.swift MCP Server
Components 23
CLI and Commands
- CLI Entry
Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift - Command Router
Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift - Capture Commands
Apps/CLI/Sources/PeekabooCLI/Commands/Core/CaptureCommand.swift - Configuration
Apps/CLI/Sources/PeekabooCLI/Commands/Core/ConfigCommand.swift - Permission Commands
Apps/CLI/Sources/PeekabooCLI/Commands/Core/PermissionsCommand.swift
Observation and Automation
- Screen Observation
Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift - Accessibility Inspection
Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand+DetectionPipeline.swift - UI Actions
Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ActionCommand.swift - macOS Controls
Apps/CLI/Sources/PeekabooCLI/Commands/System/WindowCommand.swift
Agent and MCP
- Agent Command
Apps/CLI/Sources/PeekabooCLI/Commands/AI/AgentCommand.swift - Agent Sessions
Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent/PeekabooAgentService+SessionLifecycle.swift - MCP Server
Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift - Browser MCP
Core/PeekabooCore/Sources/PeekabooAgentRuntime/Browser/BrowserMCPSessionManager.swift
Menu-Bar App
- Menu-Bar App
Apps/Mac/Peekaboo/PeekabooApp.swift - Status Bar UI
Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift - Session Chat UI
Apps/Mac/Peekaboo/Features/Main/SessionChatView.swift
Runtime Services
- Runtime Factory
Apps/CLI/Sources/PeekabooCLI/Commands/Base/Runtime/RuntimeServiceFactory.swift - Capture Engine
Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Capture/ScreenCaptureEngineSupport.swift - Snapshot Storage
Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Support/SnapshotStorageActor+MutationLease.swift
Other components
- User
- MCP Client
- macOS Desktop
- Model Provider
Connections 34
- User → CLI Entry: invokes
- CLI Entry → Command Router: dispatches
- Command Router → Screen Observation: dispatches
- Command Router → UI Actions: dispatches
- Command Router → Capture Commands: dispatches
- Command Router → macOS Controls: dispatches
- Command Router → Agent Command: dispatches
- Command Router → MCP Server: dispatches
- Command Router → Configuration: dispatches
- Command Router → Permission Commands: dispatches
- Screen Observation → Runtime Factory: uses services
- UI Actions → Runtime Factory: uses services
- Capture Commands → Runtime Factory: uses services
- macOS Controls → Runtime Factory: uses services
- Screen Observation → Capture Engine: captures
- Screen Observation → Accessibility Inspection: inspects
- Screen Observation → Snapshot Storage: publishes evidence
- UI Actions → macOS Desktop: performs actions
- Capture Engine → macOS Desktop: captures desktop
- macOS Controls → macOS Desktop: controls
- Agent Command → Agent Sessions: runs session
- Agent Sessions → Screen Observation: observes with tools
- Agent Sessions → UI Actions: acts with tools
- Agent Sessions → Model Provider: requests model steps
- Agent Sessions → Browser MCP: uses browser tools
- MCP Client → MCP Server: connects
- MCP Server → Screen Observation: exposes tools
- MCP Server → UI Actions: exposes tools
- MCP Server → Browser MCP: serves browser tools
- User → Menu-Bar App: uses
- Menu-Bar App → Status Bar UI: shows controls
- Status Bar UI → Session Chat UI: opens sessions
- Session Chat UI → Agent Sessions: continues sessions
- Configuration → Model Provider: configures access