# openclaw/peekaboo architecture

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

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

## Overview

Peekaboo is a macOS automation product with a CLI, menu-bar app, agent, and MCP interface. Its central loop is to observe a screen or app, inspect structured UI state, then perform targeted actions and report results. The graph preserves the documented capture, interaction, system-control, agent, MCP/browser, and desktop-app capabilities. Some subsystem links are dashed because their implementation was not sampled; README statements establish the user-facing capabilities, not all internal call paths.

Main entry points: [`Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift`](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift) (Command routing), [`Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift`](https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift) (Menu-bar app), [`Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift`](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift) (Observe screen), [`Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent`](https://github.com/openclaw/peekaboo/tree/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent) (Agent sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and commands"]
  node_entry["CLI entry point"]
  node_router["Command routing"]
  node_see["Observe screen<br/>[SeeCommand.swift]"]
  node_capture["Capture workflow"]
  node_interact["UI interactions"]
  node_system["macOS controls"]
  node_config["Configuration"]
end

subgraph group_automation["Desktop automation"]
end

subgraph group_agent["Agent and MCP"]
  node_agentui["Agent command<br/>[AgentCommand.swift]"]
  node_agentservice["Agent sessions"]
  node_browser["Browser MCP"]
  node_mcp["MCP interface<br/>[MCPCommand.swift]"]
end

subgraph group_app["Mac app"]
  node_macapp["Menu-bar app"]
  node_agentuiapp["Session UI"]
  node_settings["App settings<br/>[Settings.swift]"]
  node_inspector["Visual inspector"]
  node_visualizer["Visual overlays"]
  node_permissions["Permissions<br/>[Permissions.swift]"]
end

subgraph group_core["Shared runtime"]
  node_snapshot["Snapshot management"]
  node_snapshotstore[("Snapshot storage")]
  node_models["Window and app models<br/>[Application.swift]"]
  node_bridge["Bridge client"]
  node_runtime["Service runtime"]
end

node_user(("User or client"))

node_user -->|"invokes"| node_entry
node_entry -.->|"routes commands"| node_router
node_router -.->|"dispatches"| node_see
node_router -.->|"dispatches"| node_capture
node_router -.->|"dispatches"| node_interact
node_router -.->|"dispatches"| node_system
node_router -.->|"dispatches"| node_config
node_see -->|"stores observations"| node_snapshot
node_see -->|"uses window data"| node_models
node_interact -.->|"uses snapshots"| node_snapshot
node_snapshot -->|"persists leases"| node_snapshotstore
node_user -->|"requests workflow"| node_agentui
node_agentui -.->|"runs agent"| node_agentservice
node_agentservice -.->|"dispatches browser tools"| node_browser
node_user -->|"connects client"| node_mcp
node_mcp -.->|"exposes tools"| node_agentservice
node_user -->|"uses app"| node_macapp
node_macapp -->|"opens sessions"| node_agentuiapp
node_macapp -->|"checks permissions"| node_permissions
node_macapp -->|"reads preferences"| node_settings
node_user -->|"inspects UI"| node_inspector
node_inspector -->|"renders overlays"| node_visualizer
node_router -.->|"uses runtime services"| node_bridge
node_bridge -.->|"accesses services"| node_runtime

click node_entry "https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift"
click node_router "https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift"
click node_see "https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift"
click node_capture "https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/CaptureCommand.swift"
click node_interact "https://github.com/openclaw/peekaboo/tree/main/Apps/CLI/Sources/PeekabooCLI/Commands/Interaction"
click node_system "https://github.com/openclaw/peekaboo/tree/main/Apps/CLI/Sources/PeekabooCLI/Commands/System"
click node_config "https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/ConfigCommand.swift"
click node_snapshot "https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Core/Protocols/SnapshotManagerProtocol.swift"
click node_snapshotstore "https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Support/SnapshotStorageActor.swift"
click node_models "https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Core/Models/Application.swift"
click node_bridge "https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooBridge/PeekabooBridgeClient.swift"
click node_runtime "https://github.com/openclaw/peekaboo/tree/main/Core/PeekabooCore/Sources/PeekabooCore/Support"
click node_agentui "https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/AgentCommand.swift"
click node_agentservice "https://github.com/openclaw/peekaboo/tree/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent"
click node_browser "https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Browser/BrowserMCPSessionManager.swift"
click node_mcp "https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift"
click node_macapp "https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift"
click node_agentuiapp "https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Core/PeekabooAgent.swift"
click node_settings "https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Core/Settings.swift"
click node_inspector "https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooUICore/Sources/PeekabooUICore/Inspector/OverlayManager.swift"
click node_visualizer "https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooVisualizer/Sources/PeekabooVisualizer/Renderer/AnimationOverlayManager.swift"
click node_permissions "https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Core/Permissions.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_entry,node_router,node_see,node_capture,node_interact,node_system,node_config,node_user toneBlue
class node_agentui,node_agentservice,node_browser,node_mcp toneMint
class node_macapp,node_agentuiapp,node_settings,node_inspector,node_visualizer,node_permissions toneRose
class node_snapshot,node_snapshotstore,node_models,node_bridge,node_runtime toneIndigo
```

## Components

### CLI and commands

- [CLI entry point](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift): `Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift`
- [Command routing](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift): `Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift`
- [Observe screen](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand.swift`
- [Capture workflow](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/CaptureCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/Core/CaptureCommand.swift`
- [UI interactions](https://github.com/openclaw/peekaboo/tree/main/Apps/CLI/Sources/PeekabooCLI/Commands/Interaction): `Apps/CLI/Sources/PeekabooCLI/Commands/Interaction`
- [macOS controls](https://github.com/openclaw/peekaboo/tree/main/Apps/CLI/Sources/PeekabooCLI/Commands/System): `Apps/CLI/Sources/PeekabooCLI/Commands/System`
- [Configuration](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/Core/ConfigCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/Core/ConfigCommand.swift`

### Agent and MCP

- [Agent command](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/AI/AgentCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/AI/AgentCommand.swift`
- [Agent sessions](https://github.com/openclaw/peekaboo/tree/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent): `Core/PeekabooCore/Sources/PeekabooAgentRuntime/Agent`
- [Browser MCP](https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooAgentRuntime/Browser/BrowserMCPSessionManager.swift): `Core/PeekabooCore/Sources/PeekabooAgentRuntime/Browser/BrowserMCPSessionManager.swift`
- [MCP interface](https://github.com/openclaw/peekaboo/blob/main/Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift): `Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift`

### Mac app

- [Menu-bar app](https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift): `Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift`
- [Session UI](https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Core/PeekabooAgent.swift): `Apps/Mac/Peekaboo/Core/PeekabooAgent.swift`
- [App settings](https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Core/Settings.swift): `Apps/Mac/Peekaboo/Core/Settings.swift`
- [Visual inspector](https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooUICore/Sources/PeekabooUICore/Inspector/OverlayManager.swift): `Core/PeekabooUICore/Sources/PeekabooUICore/Inspector/OverlayManager.swift`
- [Visual overlays](https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooVisualizer/Sources/PeekabooVisualizer/Renderer/AnimationOverlayManager.swift): `Core/PeekabooVisualizer/Sources/PeekabooVisualizer/Renderer/AnimationOverlayManager.swift`
- [Permissions](https://github.com/openclaw/peekaboo/blob/main/Apps/Mac/Peekaboo/Core/Permissions.swift): `Apps/Mac/Peekaboo/Core/Permissions.swift`

### Shared runtime

- [Snapshot management](https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Core/Protocols/SnapshotManagerProtocol.swift): `Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Core/Protocols/SnapshotManagerProtocol.swift`
- [Snapshot storage](https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Support/SnapshotStorageActor.swift): `Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Support/SnapshotStorageActor.swift`
- [Window and app models](https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Core/Models/Application.swift): `Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Core/Models/Application.swift`
- [Bridge client](https://github.com/openclaw/peekaboo/blob/main/Core/PeekabooCore/Sources/PeekabooBridge/PeekabooBridgeClient.swift): `Core/PeekabooCore/Sources/PeekabooBridge/PeekabooBridgeClient.swift`
- [Service runtime](https://github.com/openclaw/peekaboo/tree/main/Core/PeekabooCore/Sources/PeekabooCore/Support): `Core/PeekabooCore/Sources/PeekabooCore/Support`

### Other components

- **User or client**

## Connections

- User or client → CLI entry point: invokes (evidence: `README.md`)
- CLI entry point → Command routing: routes commands
- Command routing → Observe screen: dispatches
- Command routing → Capture workflow: dispatches
- Command routing → UI interactions: dispatches
- Command routing → macOS controls: dispatches
- Command routing → Configuration: dispatches
- Observe screen → Snapshot management: stores observations
- Observe screen → Window and app models: uses window data (evidence: `Apps/CLI/Sources/PeekabooCLI/Commands/AI/SeeCommand+DetectionPipeline.swift`)
- UI interactions → Snapshot management: uses snapshots
- Snapshot management → Snapshot storage: persists leases
- User or client → Agent command: requests workflow (evidence: `README.md`)
- Agent command → Agent sessions: runs agent
- Agent sessions → Browser MCP: dispatches browser tools
- User or client → MCP interface: connects client (evidence: `README.md`)
- MCP interface → Agent sessions: exposes tools
- User or client → Menu-bar app: uses app (evidence: `README.md`)
- Menu-bar app → Session UI: opens sessions (evidence: `Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift`)
- Menu-bar app → Permissions: checks permissions (evidence: `Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift`)
- Menu-bar app → App settings: reads preferences (evidence: `Apps/Mac/Peekaboo/Features/StatusBar/StatusBarController.swift`)
- User or client → Visual inspector: inspects UI (evidence: `README.md`)
- Visual inspector → Visual overlays: renders overlays
- Command routing → Bridge client: uses runtime services
- Bridge client → Service runtime: accesses services (evidence: `Core/PeekabooCore/Sources/PeekabooCore/Support/RemoteSnapshotManager.swift`)
