Local in-context website review mode for agents

[harshitsinghbhandari]

Summary

I built a local, in-context website review system while iterating on a three-page static site. It worked well enough that it should become a reusable AgentLab tool.

The workflow is simple:

1. An agent builds or edits a website.
2. The user opens the site through a local review URL.
3. The user clicks directly on elements and leaves comments.
4. The agent reads the structured feedback file, applies the changes, and resolves the threads.
5. The original website ships without any review code.

This removes the usual back-and-forth of screenshots, approximate descriptions, and questions such as "which heading do you mean?"

What the prototype does

The prototype runs a small Node server bound to 127.0.0.1.

It provides:

• a Comment mode that highlights page elements on hover and intercepts clicks;
• a Browse mode that restores normal links and controls;
• comments attached directly to elements;
• numbered feedback pins across multiple pages;
• a side panel with comment threads and replies;
• resolve, reopen, edit, and delete actions;
• Markdown export;
• local JSON persistence;
• no authentication, accounts, cloud storage, or external services.

The review interface is injected only into HTML served by the local proxy. The source website is not modified, and the deployed website contains no review UI.

Reliable element anchoring

Each comment stores several ways to find its target:

1. A stable element identifier. Existing element IDs are preferred. Other elements receive deterministic local IDs based on the page, element type, heading context, and text.
2. A DOM selector fallback.
3. A normalized text and element-type fallback.
4. The click position as a percentage of the target element, so the pin stays near the original point.

When a page changes slightly, the client tries these strategies in order. If it recovers an element through a fallback, the thread is marked as relocated. Comments that can no longer be placed remain in the feedback list instead of disappearing.

Architecture

The prototype has three small parts:

Local review server

• Serves an existing static directory.
• Injects the review stylesheet and script into local HTML responses.
• Exposes a localhost-only comments API.
• Writes updates atomically to a JSON file.
• Rejects non-local origins.

Browser annotation client

• Discovers commentable elements.
• Generates stable anchor metadata.
• Draws hover outlines and numbered pins.
• Manages Comment and Browse modes.
• Displays composers, threads, and page feedback.

Feedback store

Each record contains the page path, anchor strategies, comment body, status, timestamps, and replies. The format is readable by both humans and coding agents.

Why this belongs in AgentLab

This creates a direct visual feedback loop between a human and a coding agent.

The important part is not only annotation. It is that the feedback becomes structured local state that an agent can inspect and act on. A user can review several pages, say "fix the open comments," and the agent has precise targets plus the requested changes.

It is useful for:

• landing pages and documentation sites;
• frontend redesigns;
• reviewing responsive states;
• iterating on generated interfaces;
• checking copy and hierarchy in context;
• handing a batch of visual changes to an agent without writing a separate brief.

Proposed tool

A first version could be a small CLI:

agentlab review ./dist

It would print and optionally open a local review URL:

Review: http://127.0.0.1:4173/
Feedback: ~/.agentlab/reviews/<project>/comments.json

Useful commands could include:

agentlab review ./dist
agentlab review comments
agentlab review export --format markdown
agentlab review clear-resolved

The feedback JSON should remain easy for any coding agent to read without a special SDK. A later MCP tool or skill could expose operations such as listing open comments, resolving a thread, or locating the referenced source component.

Suggested first scope

Keep the first release local and single-user:

• local directory serving;
• support for multiple routes;
• Comment and Browse modes;
• stable anchors with selector and text fallbacks;
• threads and resolution status;
• JSON persistence and Markdown export;
• zero changes to the reviewed website;
• minimal or zero runtime dependencies.

Defer collaboration, hosted review links, authentication, screenshots, file attachments, notifications, and framework-specific source mapping.

Next step

Package the working prototype as a standalone CLI, test it against static sites and common dev servers, then add an agent-facing command for reading and resolving open feedback.