Studio Code /annotate and the two steps it skips

The pitch is that the screenshot loop dies. WordPress.com ran a post from WordCamp Europe about Studio Code /annotate: type the command, a browser window opens, click the elements you want changed, attach a note to each, send the batch back, and the agent applies every edit in one pass. Run it while a client talks and their changes land on your local site before the call ends. I believe the clicking half of that. The half I’d argue with is everything after the call, because two steps of the loop still belong to you: the review and the deploy.

What /annotate fixes

The loop the post describes (screenshot, arrows, upload, repeat) is slow for a reason that has nothing to do with screenshots. Arrows are ambiguous. You point at a rendered page and the agent has to guess which element you mean from pixels, at whatever viewport you happened to capture. A lot of the round trips are the agent re-asking a question you thought you had already answered.

/annotate swaps the guess for a selection. You click the element, so the agent gets a concrete target rather than a picture of one. The batching matters almost as much, which the post doesn’t spell out: six notes sent together get applied with one shared understanding of the page, while six sequential requests can each undo the previous fix. I’ve had an agent correct a heading size in pass three and break it again in pass five, because each request only ever saw its own note.

So for visual passes I’d use it without hesitation: spacing, type scale, button labels, template layout, anything you can verify by looking. Pointing beats describing there.

The call becomes the review

The best idea in the post is running the annotation pass while you’re on a call with the client. It’s also the part I’d run differently. If edits land while the client is still talking, you lose the one artifact that keeps a project sane: an agreed record of what was asked for.

Verbal notes captured as clicks dissolve into a diff. The client watches changes appear in under a minute and resets their sense of what a change costs, and every later estimate gets measured against that. And nobody reads the diff, which is the part that bites. Agentic edits routinely touch more than the note asked for. A note about padding can come back with a rewritten template part, a renamed class, a change in theme.json. On a store, that’s how a visual tweak ships a layout change to the checkout page.

My version keeps the capture and drops the shipping. Run it on the call, collect everything, tell the client the changes are queued. Read the diff once the call is over, then push. You still skip the screenshots, and you still do the reading.

The push assumes your stack

The post ends with pushing the updated local site to the client’s live WordPress.com site in a few clicks. That step exists because Studio Sync supports WordPress.com sites on paid plans and Pressable sites with Jetpack, and nothing else. If the client is on Kinsta, SiteGround, or a VPS (most of mine are), that ending doesn’t apply and you’re back to git, rsync, or the host’s staging push.

So the feature is narrower than the post makes it sound. /annotate is feedback capture, and the deploy is still yours. There’s a detail in the sync docs worth stealing anyway. Selective sync can push a single theme or plugin instead of the whole site, which is exactly what you want after a visual pass, because pushing a local database over a live store erases whatever product edits your shop manager made that morning. If you want a wider view of which WordPress.com tooling reaches a self-hosted site at all, I wrote about that separately.

How I’d run a session

Studio Code is in beta and tokens are unlimited during the beta, per the announcement, so cost isn’t a reason to wait. The setup I’d use for a client session:

  • Pull the live site into Studio before the call, or at least the templates you plan to discuss. Drift is the risk: a local copy two updates behind means the client is annotating a page that no longer exists.
  • Annotate freely during the call and ship nothing while anyone is watching.
  • After the call, read the diff before anything leaves the machine.
cd /path/to/studio-site
git status --short
git diff --stat

If the site folder isn’t a git repository yet, make it one before the first session. The diff is your only honest record of what the agent changed, and diff –stat gives you the shape of it in a second. If you can’t explain something in there, don’t merge it yet. This is the same discipline I lean on in any local-to-staging workflow, agent or no agent.

What I’d still write down

Clicking identifies the element, but it doesn’t carry constraints. “Make this tighter” as a click gets you tighter, and tighter may break the sticky header. “Keep the sticky header under 56px” needs a sentence, and so does anything touching data, pricing, or checkout logic.

The split I use: if I can confirm the fix by looking at the page, annotate it. If I have to test it, write it down and keep it out of the batch.

If you want this loop set up for your team, from pulling a live store into Studio to a diff review step that runs before anything deploys, that’s the kind of work I take on, so feel free to reach out.

One last deploy detail from the docs that saves trouble later: Studio honors a .deployignore file at the site root on every push, using gitignore syntax. Put node_modules, build folders, and anything generated in it, so a theme-only sync after a session doesn’t carry dependencies and build output up the wire.

author avatar
Ahmad Wael
I'm a WordPress and WooCommerce developer with 15+ years of experience building custom e-commerce solutions and plugins. I specialize in PHP development, following WordPress coding standards to deliver clean, maintainable code. Currently, I'm exploring AI and e-commerce by building multi-agent systems and SaaS products that integrate technologies like Google Gemini API with WordPress platforms, approaching every project with a commitment to performance, security, and exceptional user experience.

Leave a Comment