Point at your running app, say what should change, and your coding agent gets the request with the evidence: source file and line, selector, screenshot, console, network, recording, and performance.
Dev-only browser annotation overlay for Vite apps that sends picked elements, captures, and prompts to Claude Code and Codex through an MCP server.
2026-11-08
ดาว
—
เครื่องมือ
—
อัปไทม์
—
pk-annotator is a dev-only overlay for Vite and React apps. Anyone reviewing the dev build can pick elements, draw, screenshot, or record, then write a prompt and press Send. The annotation lands in a local file store that Claude Code, Codex, or Pi read through the bundled pka-mcp server, and the agent's replies appear on the page. Nothing ships in a production build. While the overlay is closed, the page keeps bounded console, error, and network capture and, after this tab sends an annotation, follows its status and replies; the overlay UI and performance observers load when you use them.
Install
Requires Node 24+, Vite 8, and React 19. Yarn 2+ also requires nodeLinker: node-modules in .yarnrc.yml; Plug’n’Play is not supported.
Ask your agent. Paste this into Claude Code, Codex, or Pi from the project root:
Set up pk-annotator in this project by following https://pk-annotator.paulbkim.dev/agents.md
Or run the installer from the project root. It adds the dev dependency with your package manager and registers pka-mcp with Claude Code when claude is installed:
curl -fsSL https://pk-annotator.paulbkim.dev/install.sh | sh
Then add the plugin and mount the overlay as below. To install by hand instead, run pnpm add -D pk-annotator (or the npm, Yarn, or Bun equivalent) in the workspace root.
// client entry, before React renders
let rootOptions = {};
if (import.meta.env.DEV) {
try {
const { mount } = await import("pk-annotator/overlay");
rootOptions = mount({ hot: import.meta.hot!, theme: "system" }).reactRootOptions;
} catch (cause) {
console.error("pk-annotator did not load; the page runs without it", cause);
}
}
createRoot(document.getElementById("root")!, rootOptions).render(<App />);
// or: hydrateRoot(document, <App />, rootOptions);
Start the dev server and open the overlay with the launcher button or Alt+Shift+A. If the page sets a Content-Security-Policy, allow img-src data: blob: for screenshots.
Connect an agent
Choose Connect agent in the overlay's menu. It copies a prompt with the exact pka-mcp command for this page; paste it into your agent session. To register by hand from the project root:
claude mcp add pka --scope project -- node_modules/.bin/pka-mcp # Claude Code, .mcp.json
codex mcp add pka -- "$PWD/node_modules/.bin/pka-mcp" --root "$PWD" # Codex, global
Codex keeps servers in its global config, so that entry points at one project. Also set tool_timeout_sec = 1830 under [mcp_servers.pka] in ~/.codex/config.toml, so a long wait_for_annotation is not cut off at the 300-second default. For Pi, add { "mcpServers": { "pka": { "command": "node_modules/.bin/pka-mcp", "exposure": "direct" } } } to .pi/mcp.json.
The agent calls wait_for_annotation, claims what you send with set_status, answers with reply, and reads page errors with get_errors. While it is connected, the overlay takes on Claude's or Codex's look.
In Claude Code, each annotation can instead appear in the session the moment you send it. Start Claude Code with pka as a channel and confirm its prompt:
claude --dangerously-load-development-channels server:pka
Channels are a Claude Code research preview, and Team and Enterprise organizations must enable them. Annotations that were waiting before the session started are counted, not sent.
Use
Group
Tools
Pick
Select (Shift for several), Box, Lasso, Text
Capture
Screenshot with crop, area recording as GIF or WebM
Annotate
Freehand, Rectangle, Circle
Debug
Console, Network, Performance
Settings
History, English/한국어, Exit
Pick and Capture tools open the prompt editor; a finished drawing becomes a screenshot mark stacked for Send. Send at once, or Save marks and send them together. Text highlights the page text you select and sends it as a quote with its element, for fixing that exact wording. Element and capture badges in the text become [element n] and [attachment n: label] references for the agent. Without a connected agent, Send also copies the annotation as Markdown.
CLI
pka list | get <id> | watch --once | status <id> <state> | reply <id> <text> | errors | prune | lab
Every command takes --json and --root DIR; run pka --help for options. pka lab replays a recording against a production build and writes a performance verdict (needs Playwright).
More
Reference: plugin options, theming, store location, claims, and the CLI in detail.
Design: the behavior, resource budget, and security contract.
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
Pk Annotator ต้องใช้ API key ไหม?
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Pk Annotator ใช้ทรานสปอร์ตแบบใด?
Pk Annotator ทำงานแบบโลคัลผ่าน stdio
Pk Annotator ถูกตรวจสอบล่าสุดเมื่อใด?
ตรวจสอบล่าสุดเมื่อ 2026-11-08 Dev-only browser annotation overlay for Vite apps that sends picked elements, captures, and prompts to Claude Code and Codex through an MCP server.