Peekaboo MCP

--- summary: 'Perform gesture-style drags via peekaboo swipe' read_when: - 'animating trackpad-like swipes between coordinates or elements' - 'needing smooth, timed drags for carousels/cover flow UI' --- # `peekaboo swipe` `swipe` drives `AutomationServiceBridge.swipe` to move from one point to another over a fixed duration. You can describe the endpoints via element IDs (from `see`) or raw coordinates, which makes it flexible for both deterministic automation and exploratory scripts. ## Key options | Flag | Description | | --- | --- | | `--from <id>` / `--from-coords x,y` | Source location (ID requires a valid session). | | `--to <id>` / `--to-coords x,y` | Destination location (also supports IDs or literal coordinates). | | `--session <id>` | Needed whenever you reference IDs so the command can look up bounds. Auto-resolves to the most recent session if omitted. | | `--duration <ms>` | Default 500 ms; controls how long the swipe lasts. | | `--steps <count>` | Number of intermediate points for smoothing (default 20). | | `--right-button` | Currently rejected — the implementation throws a validation error because right-button drags are not yet wired up. | | `--profile <linear\|human>` | Use `human` for gesture traces that look like real pointer motion. | ## Implementation notes - The command validates that both ends are provided (mixing IDs and coordinates is fine) before doing any work. - Element lookups reuse the `[waitForElement + bounds.midpoint]` flow with a 5 s timeout, so swipes tolerate elements that pop in slightly late. - Coordinate parsing accepts `"x,y"` with optional whitespace; invalid strings result in immediate validation errors. - After issuing the swipe it waits ~0.1 s before reporting success to give AppKit time to settle (matching what integration tests expect). - JSON output surfaces both endpoints and the computed Euclidean distance, which is handy when you need to assert coverage in tests. - `--profile human` enables adaptive durations/steps plus jittery arcs; see `docs/human-mouse-move.md` for the generator’s behavior. ## Examples ```bash # Swipe between two element IDs captured by `see` polter peekaboo -- swipe --from card_1 --to card_2 --duration 650 --steps 30 # Drag from coordinates (x1,y1) to (x2,y2) polter peekaboo -- swipe --from-coords 120,880 --to-coords 120,200 # Human-style swipe with adaptive easing polter peekaboo -- swipe --from-coords 80,640 --to-coords 820,320 --profile human # Mix coordinate → element drag using the most recent session polter peekaboo -- swipe --from-coords 400,400 --to drawer_toggle ``` ## Troubleshooting - Verify Screen Recording + Accessibility permissions (`peekaboo permissions status`). - Confirm your target (app/window/selector) with `peekaboo list`/`peekaboo see` before rerunning. - Re-run with `--json-output` or `--verbose` to surface detailed errors.