# steipete/peekaboo architecture

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

- Interactive diagram: https://gitdiagram.com/steipete/peekaboo
- Repository: https://github.com/steipete/peekaboo

## Overview

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: [`Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift`](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift) (Command Router), [`Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift`](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift) (Screen Observation), [`Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent/PeekabooAgentService+SessionLifecycle.swift`](https://github.com/steipete/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent/PeekabooAgentService%2BSessionLifecycle.swift) (Agent Sessions), [`Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift`](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift) (MCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Commands"]
  node_cli_entry["CLI Entry"]
  node_router["Command Router"]
  node_capture_cmd["Capture Commands"]
  node_config_cmd["Configuration"]
  node_permissions["Permission Commands"]
end

subgraph group_automation["Observation and Automation"]
  node_observe["Screen Observation<br/>[SeeCommand.swift]"]
  node_inspect["Accessibility Inspection"]
  node_interact["UI Actions"]
  node_system_control["macOS Controls"]
end

subgraph group_agent["Agent and MCP"]
  node_agent_cmd["Agent Command<br/>[AgentCommand.swift]"]
  node_agent_service["Agent Sessions"]
  node_mcp_cmd["MCP Server<br/>[MCPCommand.swift]"]
  node_browser_mcp["Browser MCP"]
end

subgraph group_macapp["Menu-Bar App"]
  node_mac_app["Menu-Bar App<br/>[PeekabooApp.swift]"]
  node_status_bar["Status Bar UI"]
  node_session_ui["Session Chat UI"]
end

subgraph group_runtime["Runtime Services"]
  node_runtime_factory["Runtime Factory"]
  node_capture_engine["Capture Engine"]
  node_snapshot_store[("Snapshot Storage")]
end

node_user(("User"))
node_mcp_client(("MCP Client"))
node_macos["macOS Desktop"]
node_model_provider["Model Provider"]

node_user -->|"invokes"| node_cli_entry
node_cli_entry -->|"dispatches"| node_router
node_router -->|"dispatches"| node_observe
node_router -->|"dispatches"| node_interact
node_router -->|"dispatches"| node_capture_cmd
node_router -->|"dispatches"| node_system_control
node_router -->|"dispatches"| node_agent_cmd
node_router -->|"dispatches"| node_mcp_cmd
node_router -->|"dispatches"| node_config_cmd
node_router -->|"dispatches"| node_permissions
node_observe -->|"uses services"| node_runtime_factory
node_interact -->|"uses services"| node_runtime_factory
node_capture_cmd -->|"uses services"| node_runtime_factory
node_system_control -->|"uses services"| node_runtime_factory
node_observe -->|"captures"| node_capture_engine
node_observe -->|"inspects"| node_inspect
node_observe -->|"publishes evidence"| node_snapshot_store
node_interact -->|"performs actions"| node_macos
node_capture_engine -->|"captures desktop"| node_macos
node_system_control -->|"controls"| node_macos
node_agent_cmd -->|"runs session"| node_agent_service
node_agent_service -->|"observes with tools"| node_observe
node_agent_service -->|"acts with tools"| node_interact
node_agent_service -->|"requests model steps"| node_model_provider
node_agent_service -.->|"uses browser tools"| node_browser_mcp
node_mcp_client -->|"connects"| node_mcp_cmd
node_mcp_cmd -->|"exposes tools"| node_observe
node_mcp_cmd -->|"exposes tools"| node_interact
node_mcp_cmd -->|"serves browser tools"| node_browser_mcp
node_user -->|"uses"| node_mac_app
node_mac_app -->|"shows controls"| node_status_bar
node_status_bar -->|"opens sessions"| node_session_ui
node_session_ui -->|"continues sessions"| node_agent_service
node_config_cmd -->|"configures access"| node_model_provider

click node_cli_entry "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift"
click node_router "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift"
click node_capture_cmd "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/CaptureCommand.swift"
click node_config_cmd "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/ConfigCommand.swift"
click node_permissions "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/PermissionsCommand.swift"
click node_observe "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift"
click node_inspect "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand%2BDetectionPipeline.swift"
click node_interact "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ActionCommand.swift"
click node_system_control "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/System/WindowCommand.swift"
click node_agent_cmd "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/AgentCommand.swift"
click node_agent_service "https://github.com/steipete/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent/PeekabooAgentService%2BSessionLifecycle.swift"
click node_mcp_cmd "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift"
click node_browser_mcp "https://github.com/steipete/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Browser/BrowserMCPSessionManager.swift"
click node_mac_app "https://github.com/steipete/peekaboo/blob/main/Apps/Mac/Peekaboo/PeekabooApp.swift"
click node_status_bar "https://github.com/steipete/peekaboo/blob/main/Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift"
click node_session_ui "https://github.com/steipete/peekaboo/blob/main/Apps/Mac/Peekaboo/Features/Main/SessionChatView.swift"
click node_runtime_factory "https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Base/Runtime/RuntimeServiceFactory.swift"
click node_capture_engine "https://github.com/steipete/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Capture/ScreenCaptureEngineSupport.swift"
click node_snapshot_store "https://github.com/steipete/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Support/SnapshotStorageActor%2BMutationLease.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_cli_entry,node_router,node_capture_cmd,node_config_cmd,node_permissions,node_user,node_mcp_client toneBlue
class node_observe,node_inspect,node_interact,node_system_control toneAmber
class node_agent_cmd,node_agent_service,node_mcp_cmd,node_browser_mcp toneMint
class node_mac_app,node_status_bar,node_session_ui toneRose
class node_runtime_factory,node_capture_engine,node_snapshot_store,node_macos,node_model_provider toneIndigo
```

## Components

### CLI and Commands

- [CLI Entry](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift): `Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift`
- [Command Router](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift): `Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift`
- [Capture Commands](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/CaptureCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/Core/CaptureCommand.swift`
- [Configuration](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/ConfigCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/Core/ConfigCommand.swift`
- [Permission Commands](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/PermissionsCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/Core/PermissionsCommand.swift`

### Observation and Automation

- [Screen Observation](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift`
- [Accessibility Inspection](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand%2BDetectionPipeline.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand+DetectionPipeline.swift`
- [UI Actions](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ActionCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/Interaction/ActionCommand.swift`
- [macOS Controls](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/System/WindowCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/System/WindowCommand.swift`

### Agent and MCP

- [Agent Command](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/AgentCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/AI/AgentCommand.swift`
- [Agent Sessions](https://github.com/steipete/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent/PeekabooAgentService%2BSessionLifecycle.swift): `Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent/PeekabooAgentService+SessionLifecycle.swift`
- [MCP Server](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift`
- [Browser MCP](https://github.com/steipete/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Browser/BrowserMCPSessionManager.swift): `Core/PeekabooCore/Sources/PeekabooAgentRuntime/Browser/BrowserMCPSessionManager.swift`

### Menu-Bar App

- [Menu-Bar App](https://github.com/steipete/peekaboo/blob/main/Apps/Mac/Peekaboo/PeekabooApp.swift): `Apps/Mac/Peekaboo/PeekabooApp.swift`
- [Status Bar UI](https://github.com/steipete/peekaboo/blob/main/Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift): `Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift`
- [Session Chat UI](https://github.com/steipete/peekaboo/blob/main/Apps/Mac/Peekaboo/Features/Main/SessionChatView.swift): `Apps/Mac/Peekaboo/Features/Main/SessionChatView.swift`

### Runtime Services

- [Runtime Factory](https://github.com/steipete/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Base/Runtime/RuntimeServiceFactory.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/Base/Runtime/RuntimeServiceFactory.swift`
- [Capture Engine](https://github.com/steipete/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Capture/ScreenCaptureEngineSupport.swift): `Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Capture/ScreenCaptureEngineSupport.swift`
- [Snapshot Storage](https://github.com/steipete/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Support/SnapshotStorageActor%2BMutationLease.swift): `Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Support/SnapshotStorageActor+MutationLease.swift`

### Other components

- **User**
- **MCP Client**
- **macOS Desktop**
- **Model Provider**

## Connections

- 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