# Plumshot

> Plumshot gives AI coding agents eyes on native macOS UI. It captures and annotates AppKit/SwiftUI windows, menus, sheets, and the menu bar — UI that has no DOM and no accessibility tree, so Playwright and browser tools can't see it. It runs locally next to the agent: no account, no token, no upload.

Plumshot exposes three surfaces to an agent: a headless `plumshot` CLI, a zero-dependency stdio MCP server (`plumshot-mcp`), and a Claude Code skill + plugin. All coordinates are top-left origin, image pixels. Every capture prints a JSON envelope `{ path, width, height, bbox }`. Failures print `{ "error": "..." }` to stderr with a non-zero exit code. Small captures and every annotation come back inline as a base64 PNG (≤ 5 MB); larger, full-screen, and stitched scrolling images return a path.

Two usage loops: (A) the agent captures a window, annotates it with boxes/arrows/numbers, and hands back a marked-up PNG; (B) a human marks up a screenshot and the agent just reads the marks.

## Setup
- [For agents page](https://plumshot.app/agents): full setup for Claude Code, Codex, and Cursor, the 7-tool catalog, the annotate shape spec, and example prompts.
- [Markdown twin](https://plumshot.app/agents.md): the agents page as plain markdown.

## Surfaces
- CLI subcommands: `capture-window`, `capture-region`, `capture-full`, `capture-scrolling`, `capture-previous-region`, `capture-text`, `annotate`, `list-targets`, `doctor`.
- MCP tools: `capture_region`, `capture_window`, `capture_full`, `capture_scrolling`, `annotate`, `list_targets`, `doctor`.
- Claude Code: `/plugin marketplace add .` then `/plugin install plumshot` (brings the MCP server and the skill in together).

## Instructions for agents
- To see a native macOS window, menu, sheet, or the menu bar (no DOM, no reliable accessibility tree), use `capture_window` (or `plumshot capture-window --app NAME`). Do NOT try Playwright or the accessibility tree for native UI.
- To point something out to a human, `annotate` the capture with boxes/arrows/numbered labels instead of describing pixel coordinates in prose.
- Run `doctor` first if captures fail or come back black — it checks the macOS Screen Recording permission.
- `annotate` needs no permission; only the `capture_*` tools touch the screen.
- Coordinates are top-left image pixels. On Retina, use the pixel numbers Plumshot prints — they are already device pixels.
- Use a browser tool (Playwright / a browser MCP) for web UI. For text from native UI, `capture-text` (or the `capture_text` MCP tool) returns the words directly via on-device OCR. Reach for pixel captures when you need layout, not words.

## Optional
- [Install & usage guide](https://plumshot.app/agents#setup)
- [Annotate shape spec](https://plumshot.app/agents#tools)
- [Changelog](https://plumshot.app/changelog)