没有 DOM · 没有无障碍树 · 没有浏览器界面

让你的编程 Agent
看见 macOS。

Plumshot 自带命令行工具，让编程 Agent 截取并标注浏览器工具看不见的原生窗口、菜单和 Sheet。完全在本地运行，无需账号，也无需 API token。

plumshot capture-window --app "MyApp" --out /tmp/shot.png接入你的 Agent

查看命令

macOS 14 Sonoma 或更高版本 · 屏幕录制权限 · 任何能跑 shell 的 Agent · 100% 本地处理

你的 Agent 交回来的东西 —— 一张画好标注的 PNG，而不是一段像素坐标。

截图变成一场对话

Loop A

Agent 展示给你看

你的 Agent 截下一个窗口，用方框、箭头和编号标出问题，交回一张标注好的 PNG。每条截图命令都以 JSON 输出图片路径，能打开图片的 Agent 都能直接看到。

capture-window
annotate
给人看

Loop B

你展示给 Agent 看

你自己在截图上做标记 —— 用 Plumshot、预览都行 —— Agent 直接读懂这些标记，照着去做。不用截屏，也不需要权限。

你来标注
Agent 读取 PNG
Agent 执行

能跑 shell 的 Agent，现在就能用

编程 Agent 本来就会执行 shell 命令，可以直接驱动 CLI，不用配置 MCP。

现已可用

无头 CLI

plumshot …

每次截取都以 JSON 输出 { path, width, height, bbox }。CLI 就是签过名的应用二进制本身，不用另装。

即将推出

MCP 服务器 + Claude Code 插件

stdio MCP · Claude Code 技能

把同一套命令做成原生 MCP 工具，再配一个 Claude Code 技能。上线之前，CLI 能做同样的事。

想在上线时收到通知？写信到 support@plumshot.app

5 步给你的 Agent 装上眼睛

装好应用，在 PATH 里放一个两行的包装脚本，再告诉 Agent 它在哪儿。

安装 Plumshot
下载 DMG，把 Plumshot 拖进「应用程序」。需要 macOS 14 Sonoma 或更高版本。
下载免费试用
给终端或 Agent 应用授予屏幕录制权限
macOS 检查的是运行 plumshot 的应用（终端、iTerm、Cursor 等），不是 Plumshot 本身。在「系统设置 ▸ 隐私与安全性 ▸ 录屏与系统录音」（macOS 14 上叫「屏幕录制」）中启用那个应用（列表里没有就点 + 按钮添加），然后退出并重新打开它。第 4 步的 plumshot doctor 会写出是哪个应用。capture-scrolling 的自动滚动还需要给同一个应用开「辅助功能」权限；annotate 不需要任何权限。
3
把 CLI 加入 PATH
```
mkdir -p ~/.local/bin
printf '#!/bin/sh\nexec /Applications/Plumshot.app/Contents/MacOS/Plumshot "$@"\n' > ~/.local/bin/plumshot
chmod +x ~/.local/bin/plumshot
```
这几行会写入一个两行的包装脚本，由它调用应用里的二进制。如果 ~/.local/bin 还不在 PATH 里，把 export PATH="$HOME/.local/bin:$PATH" 加进 ~/.zshrc，再新开一个终端窗口。

验证

plumshot doctor
  screen recording (TCC): granted ✓
  accessibility (AX):     not granted (optional)
  bundle id:              com.plumshot.app
  binary:                 /Applications/Plumshot.app/Contents/MacOS/Plumshot
  signing:                Developer ID Application: … ✓
  host app (likely):      Terminal (com.apple.Terminal)
  license:                trial not started; the first capture starts it

再做一次冒烟测试：截一个窗口，并列出屏幕上的目标。

plumshot capture-window --app Finder --out /tmp/cap.png
plumshot list-targets

告诉你的 Agent

把下面这段贴进 CLAUDE.md（Claude Code）或 AGENTS.md（Codex、Cursor 等），Agent 就知道有这个 CLI，也知道什么时候该用它。

## Native macOS screenshots (Plumshot)
- `plumshot` captures and annotates native macOS UI (windows, menus, sheets,
  the menu bar) that browser tools can't see. `plumshot --help` lists every
  command and flag; https://plumshot.app/agents.md has the full guide.
- See a window: `plumshot capture-window --app "MyApp" --out /tmp/shot.png`,
  then open the PNG. Captures print JSON: {"path", "width", "height", "bbox"}.
- Point at something: pipe {"shapes": [...]} (box, arrow, text, number,
  highlight, blur; top-left image pixels) into
  `plumshot annotate --in /tmp/shot.png --out /tmp/marked.png --shapes -`.
- Read words, not pixels: `plumshot capture-text --app "MyApp"` returns
  {"text", "chars"} via on-device OCR.
- Errors print {"error": "..."} on stderr with a non-zero exit. If a capture
  fails or comes back black, run `plumshot doctor`.
- Use a browser tool for web pages; use plumshot for native macOS UI.

关于许可证：doctor、list-targets、version 和 help 免费。annotate 和所有 capture-* 命令包含在 3 天全功能试用里（从第一次截图开始计时），试用结束后需要 $9.90 的一次性许可证。

屏幕录制是唯一的门槛

只有截取命令需要权限：屏幕录制，授予你的终端或 Agent 应用。不需要完全磁盘访问，「辅助功能」也只在滚动截图自动滚动时才用到。

截图只写到 --out 指定的本地文件，不上传任何内容。
annotate 不需要任何权限 —— 它只在你已有的 PNG 上画图。
capture-scrolling 的自动滚动还需要同一个应用有「辅助功能」权限；用 plumshot doctor 检查，或者传 --no-auto-scroll。
设置 PLUMSHOT_SANDBOX_ROOT 可以把 --in、--out 和 --shapes 限制在一个目录里。默认关闭。
分享前先遮盖：用 blur 形状盖住敏感信息（style 设为 blackOut 可彻底遮盖）。

命令一览

所有坐标以左上角为原点、图片像素为单位。截取命令在 stdout 输出 JSON 信封 { path, width, height, bbox }；失败时在 stderr 输出 { "error": … } 并以非零状态退出。plumshot --help 列出全部参数。

命令	参数	输出
`capture-window`	`--app <名称>（子串匹配，不分大小写）--out <png> [--window <标题>]`	JSON 信封 · 取匹配的最大窗口
`capture-region`	`--rect x,y,w,h --out <png> [--display-id ID \| --display N]`	JSON 信封
`capture-previous-region`	`--out <png>`	JSON 信封 · 重复上次区域（CLI 或应用里的）
`capture-full`	`--out <png> [--display-id ID \| --display N]`	JSON 信封 · 默认光标所在的屏幕
`capture-scrolling`	`--rect x,y,w,h --out <png> [--max-seconds N（默认 30）] [--idle-seconds N（默认 3）] [--no-auto-scroll]`	JSON 信封 · 自动滚动需要辅助功能权限
`capture-text`	`--in <png> \| --rect x,y,w,h \| --app <名称> [--window <标题>]；[--no-linebreaks] [--out <png>]`	JSON { text, chars } · 端侧 OCR
`annotate`	`--in <png> --out <png> [--shapes <文件> \| -]（默认读 stdin）`	JSON 信封 · 无需权限
`list-targets`	`—`	JSON { displays, windows } · 免费
`doctor`	`—`	权限、宿主应用、签名与许可证 · 免费

标注是一份声明式形状描述

不用鼠标、不开 GUI —— 你的 Agent 用 JSON 写出箭头、方框、文字与遮盖。

shapes（左上角原点，图片像素）

{ "shapes": [
  { "type": "box",       "x": 980, "y": 60, "w": 260, "h": 96,
                         "color": "#FF3B30", "lineWidth": 3, "filled": false },
  { "type": "arrow",     "from": [880, 200], "to": [1000, 110] },
  { "type": "text",      "x": 700, "y": 210, "text": "label is clipped", "fontSize": 30 },
  { "type": "number",    "x": 1110, "y": 108, "n": 1 },
  { "type": "highlight", "x": 120, "y": 320, "w": 400, "h": 28 },
  { "type": "blur",      "x": 60, "y": 60, "w": 300, "h": 40,
                         "style": "pixelate|secureBlur|smoothBlur|blackOut" }
] }

默认值：颜色 #FF3B30（红），lineWidth 3，文字 fontSize 28，数字标记 36，模糊 pixelate。形状描述默认从 stdin 读取（--shapes -），也可以用 --shapes file.json 传文件。Retina 屏上直接用 Plumshot 输出的像素数值 —— 它们已经是设备像素。

实际该怎么说

照着说就行，和上面两个循环一一对应。

Loop A —— Agent 展示给你看

截取 MyApp 的偏好设置窗口，告诉我保存按钮的文字有没有被截断。
截取设置 Sheet，在坏掉的文字上画红框加箭头、标上数字 1，然后给我看。
对这个列表做一次滚动截图，检查底部几行是否正常渲染。

Loop B —— 你展示给 Agent 看

读一下 ~/shot.png —— 我画了箭头指出要修的地方。照着箭头做。
这是我标注过的截图；1 号框指的是什么？

预热

运行 plumshot doctor 和 list-targets，然后截取 MyApp 的前台窗口。

什么时候该用 Plumshot

用 Plumshot 处理

原生 AppKit/SwiftUI 窗口
NSMenu 与菜单栏
Sheet、警告框与 Popover
自绘视图与画布
拖拽预览、红绿灯按钮间距
任何没有可靠无障碍树的界面

这些场景请用别的

Web 界面 → Playwright / 浏览器 MCP（有 DOM、console、network）
纯文字提取 → capture-text 直接读出文字（端侧 OCR） —— 比把像素喂给视觉模型更省
没有显示器或屏幕录制授权的无头 CI
亚像素级对比 → 先截取，再用图像工具做 diff

原生 macOS 的典型故障

拿不准就先跑一次 plumshot doctor。

plumshot: command not found

先按第 3 步建好包装脚本，并确认 ~/.local/bin 在 PATH 里（改完 ~/.zshrc 要新开终端窗口）。也可以直接调用二进制：/Applications/Plumshot.app/Contents/MacOS/Plumshot doctor。

doctor 显示 Screen Recording NOT granted

在「系统设置 ▸ 隐私与安全性 ▸ 录屏与系统录音」（macOS 14 上叫「屏幕录制」）中启用 doctor 的 host app (likely) 一行写的应用 —— 你的终端或 Agent 应用，不是 Plumshot —— 然后退出并重新打开它。如果写的是辅助进程（比如 Cursor Helper），就启用它所属的主应用。

截取结果全黑 / 空白

调用「成功」但图是黑的或空的，就是屏幕录制权限缺失的经典症状。用 plumshot doctor 确认；并确保目标在已登录的图形会话里。

No on-screen window for app=…

--app 会在当前屏幕上的窗口里按应用名做子串匹配（不分大小写）。运行 plumshot list-targets 查看准确的应用名和窗口标题。

Plumshot's trial has ended

3 天试用结束后，annotate 和 capture-* 命令需要许可证。购买 $9.90 许可证后，在 Plumshot 的「设置 → 许可证」里激活。doctor、list-targets 和 help 照常可用。

capture-scrolling 不滚动

自动滚动需要运行 plumshot 的应用有「辅助功能」权限。授予它，或者传 --no-auto-scroll 自己滚动目标。

也为 Agent 阅读而生

机器可读的孪生文档，Agent 可以直接抓取。

# Plumshot

> Plumshot is a native macOS screenshot app: full-screen, window, region, and scrolling capture; screen recording with trimming; an annotation editor with numbered steps, redaction, crop, layers, and backgrounds; on-device OCR; capture history, Quick Access, and global shortcuts. It needs macOS 14 Sonoma or later, runs on Apple Silicon and Intel, and is notarized by Apple. A license costs $9.90 once for one Mac, after a 3-day full-feature trial; there is no subscription and no account.

Plumshot also works as a command-line tool: the app's own binary runs headless commands, so AI coding agents (Claude Code, Codex, Cursor, or any agent with a shell) can capture and annotate native macOS UI that browser tools can't see. 简体中文介绍见 https://plumshot.app/zh 。

## Product
- [Home](https://plumshot.app): features, pricing, and FAQ.
- [中文主页](https://plumshot.app/zh): the same site in Simplified Chinese.

Agent 索引

按 llms.txt 约定的精炼索引：Plumshot 是什么、价格与试用、CLI、什么时候该用。

/llms.txt

# Plumshot for agents

> Give your coding agent eyes on macOS.

Plumshot's command-line tool lets AI coding agents capture and annotate native macOS 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 your agent: no account, no API token, no upload.

This is the plain-markdown twin of <https://plumshot.app/agents>.

## The two loops

Markdown 孪生页

本页的纯 Markdown 版本：可解析的命令和形状描述，而不是渲染过的 HTML。

/agents.md

不想贴片段？让你的 Agent 在第一次截图前先读一遍 https://plumshot.app/agents.md。

让你的 Agent 直面像素。

装好应用、加一个两行的包装脚本，你的 Agent 就能看见浏览器工具够不到的原生界面。

下载免费试用接入你的 Agent

完全本地 · 无需账号 · 3 天免费试用 · $9.90 一次性买断

让你的编程 Agent看见 macOS。