# Peekaboo Bridge

## Overview

OpenClaw.app can function as a **PeekabooBridge host**, enabling UI automation through the `peekaboo` CLI while leveraging existing macOS app permissions.

## Key Capabilities

The system operates as a thin broker where:

- OpenClaw.app acts as the hosting service
- The `peekaboo` command-line tool serves as the client interface
- Visual overlays remain within Peekaboo.app rather than OpenClaw

## Setup Instructions

To activate this feature, navigate to **Settings -> Enable Peekaboo Bridge** within the macOS application. Once enabled, OpenClaw initiates a local UNIX socket server; disabling it stops the host and causes `peekaboo` to revert to alternative available hosts.

## Host Discovery Sequence

Peekaboo clients attempt connection in this order:

1. Peekaboo.app (full user experience)
2. Claude.app (if present)
3. OpenClaw.app (broker alternative)

Check active hosts using:

```bash
peekaboo bridge status --verbose
```

Override socket path with:

```bash
export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
```

## Security Features

The bridge validates caller code signatures; an allowlist of TeamIDs is enforced. Request timeouts are approximately 10 seconds. Missing permissions trigger error messages rather than prompting system dialogs.

## Snapshot Management

Snapshots exist temporarily in memory with automatic expiration. Re-capture snapshots when extended retention is needed.

## Common Issues

- **Authorization errors**: Ensure proper code signing or enable `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` in debug mode
- **No hosts detected**: Launch either Peekaboo.app or OpenClaw.app and verify permission grants