Recipes

Fix a pinned bug

Someone left notes on a live page and you want them turned into commits.

Start with get_latest_review(), or get_page_bundle(targetUrl) if the feedback is spread across one page. Read the notes first and pick the Blockers and Highs — reading commits you to nothing.

For each one you take on, call get_screenshot(reviewId, commentId) to see what the reviewer meant. Opening the image takes that pin on: the server now expects you to close it before the turn ends.

Then find the code yourself — Handoff can't see your repo. A review hands you the selector and the element's computed styles; its outerHTML comes only from get_page_bundle, so reach for that one when the selector alone isn't enough to place the component. Grep for the selector's classes and ids and for the text you can read in the screenshot, then map the URL path to the route that renders it.

Change the code, build, test. Only then resolve_comment(reviewId, commentId, note), or reply_comment(…, body), which posts into the pin's thread and resolves it in one call. Both surface in a small popover on the pin, so one or two sentences plus a commit ref is the right length.

One comment, one focused change. Never resolve what you didn't fix — if you can't find the code, leave the pin open and say what blocks you.

Longer version: bug reports for AI agents.

Audit a page and file what you find

The reverse direction: your agent inspects a page and leaves the pins itself.

Call get_page_bundle(targetUrl) first — every comment on the page, closed ones included, each with its status. There is no server-side deduplication, so this read is the only thing standing between you and a second pin on a selector someone already covered.

Then create_comments(page_url, findings[]), up to twenty findings per call. Each finding needs a body and a severity of Low, Medium, High, Blocker or Redesign; give it a selector so it lands on a real element rather than only on the board — a finding without one becomes a region pin and loses its html. A finding about console output is page-level instead, and cannot also carry a selector, coordinates or html.

Each finding becomes its own review holding one comment. Authorship isn't a field on the comment: the agent's ownership stays null and the “created” event in the log is what marks it, which is why the AI badge shows both on the pin and on the board.

Longer version: AI page audits.

Gather feedback on a preview deploy

Every branch gets its own URL, and you want notes against that build, not against production.

The key a pin is filed under is origin + pathname: the query string and the hash are dropped, and a trailing slash is folded away on read, so /checkout and /checkout/ are the same page. A preview domain is a different origin, so it gets its own site — with its own board and its own public link.

One asymmetry to know: that normalisation happens on the surfaces, not in get_page_bundle, which compares targetUrl as a literal string. Copy the URL out of a review instead of typing it, or a trailing slash will hand you an empty bundle.

Longer version: preview deploy feedback.

Keep visual rework out of the bug queue

Redesign is the fifth value of the same severity field, alongside Low, Medium, High and Blocker. In a page bundle it sorts last, after every bug severity, and on the board it sits outside the danger palette — so a batch of visual work can be scheduled as a batch.

A pin anchored to an element also carries that element's computed styles, so a note about spacing arrives with the padding value that produced it. Pins without a selector — a region pin, or a console finding — have no styles line at all, which is one more reason to pass selector when your agent files findings itself.

Longer version: design review tool.

Send a review to someone outside the team

A client or a stakeholder needs to follow what was raised and what's been fixed.

The public link is issued per site, not per review: one link per origin, showing every comment left on that origin with its screenshots, notes and current status. It's read-only by construction — the endpoint behind it only reads, the page has no form of any kind, and the payload strips out who left each comment. Revoking the link closes the page.

Nothing is ever created from that page. A new pin comes from the extension, or from an agent calling create_comments with a key; the web board can only reply, change status or severity, and delete.

If the person outside your team wants to pin things themselves, they install the extension, which mints its own key without a sign-up. Their pins won't land on your board, though: without membership their feedback goes to a site of their own. An invite is what routes it to yours.

Longer version: client sign-off.

Show a teammate what you changed

Not feedback in this direction — a demonstration, captured by the agent and sent as a link.

Describe the flow and let record_walkthrough(goal, origin, steps[]) turn it into a plan file under .handoff/walkthroughs/ plus the exact local command. It captures nothing itself: the shot is taken by get-handoff walk on your machine, because a cloud server can't drive a browser.

Look at the frames, then publish with publish_walkthrough(walkthroughId, summary[]) — one line per step, covering every step, indexed from zero. Re-running the same plan file replaces the frames on the same link, so a published walkthrough updates in place.

Longer version: interactive demos.

Work through one page end to end

When a single page has accumulated a pile of notes from several people.

get_page_bundle(targetUrl) returns them grouped by severity — Blocker, High, Medium, Low, Redesign — with each element's outerHTML alongside its selector and styles, which is usually enough to locate the component without opening the page yourself.

Work down the groups in order, one comment per change. Install the pin guard (see the MCP reference) if you'd rather not rely on remembering which pins you opened: it hands them back before your turn ends.

Longer version: visual feedback for AI agents.