Reviewable HTML Workbench

A Claude Code / Codex CLI plugin that lets you review agent-generated HTML documents with inline comments — and have the agent read those comments, reply, and improve the document in the next iteration.

Overview

Agent workflows produce reports, design documents, and comparison tables — but turning those outputs into something you actually trust requires back-and-forth review. Chat-based feedback loses context: "fix the table in section 3" works once, but doesn't scale when you have dozens of comments across a long document.

Reviewable HTML Workbench solves this by putting the review conversation inside the document itself:

1. Generate — The agent produces an HTML bundle with structured sections, diagrams, and images.
2. Review — You open the preview, select any text or image, and leave a comment right where the issue is.
3. Ingest — The agent reads your comments, classifies each one, and writes replies explaining what it will change.
4. Improve — The agent updates the document, re-renders, and you see the changes in context.
5. Repeat — Keep commenting and refining until the document is ready.

Comments are attached to exact document ranges and persisted as structured JSON, so nothing is lost between iterations. When you're satisfied, export the final document as a single self-contained HTML file.

The plugin includes three skills. visual-html-renderer creates reviewable visual HTML documents. reviewable-design-doc builds review-ready design documents and feeds browser comments back into the agent workflow. plan-preview gives Plan Mode proposals a temporary HTML preview URL before implementation starts.

Features

• Inline Review Comments: select any text or image in the preview to leave a comment. Comments are highlighted in the document with margin cards showing status, replies, and threading.
• Automatic Agent Replies: when you add a comment in the browser, the agent can read the selected text and surrounding document context, then write its reply back into the same thread.
• Resolution-Gated Updates: clarification threads stay in the document until you resolve them. Once the thread is resolved, the agent can apply the agreed document changes and notify the browser.
• Plan Preview URLs: when a plan needs visual review, the agent can include a temporary Reviewable HTML Workbench preview URL directly in the plan text.
• Review Ingestion: comments are classified as actionable, clarification, already addressed, and related states so the review conversation stays structured across iterations.
• Publish & Download: switch to a clean reading view with no review UI, then download a single self-contained HTML file with all CSS and images embedded. The exported file auto-detects OS light/dark theme.
• Document Model: schema-driven document input for predictable HTML generation.
• HTML Rendering: produces index.html, copied assets, and renderer-manifest.json.
• Preview Server with Tailscale: starts a session-scoped preview server, preferring Tailscale IPv4 and falling back to 127.0.0.1; 0.0.0.0 bind is rejected.
• Dark/Light Theme: UI support for theme switching in rendered review documents.
• Diagram + Image Support: stores Mermaid sources, renders fallback diagrams, and attaches generated image assets to document model blocks.

Installation

Claude Code

Add the GitHub repository as a plugin marketplace and install:

claude plugin marketplace add u-ichi/reviewable-html-workbench
claude plugin install reviewable-html-workbench

Alternatively, clone the repository and install locally:

git clone https://github.com/u-ichi/reviewable-html-workbench.git
cd reviewable-html-workbench
claude plugins install .

For local development, run Claude Code with this plugin directory:

claude --plugin-dir /path/to/reviewable-html-workbench

Codex CLI

Add the GitHub repository as a plugin marketplace, then add the plugin. This repository's marketplace name is reviewable-html-workbench-local:

codex plugin marketplace add u-ichi/reviewable-html-workbench
codex plugin add reviewable-html-workbench@reviewable-html-workbench-local

To verify the configured marketplace name, check the left column:

codex plugin marketplace list

Or clone and register locally:

git clone https://github.com/u-ichi/reviewable-html-workbench.git
codex plugin marketplace add ./reviewable-html-workbench
codex plugin add reviewable-html-workbench@reviewable-html-workbench-local

Codex installs plugins as a whole plugin. It does not currently install only one language variant of this plugin. This plugin keeps one shared runtime and includes both English and Japanese skill instructions.

Quick Start

You use Reviewable HTML Workbench by asking Claude Code or Codex CLI for a reviewable artifact. You do not normally run the Python commands yourself; the agent uses them behind the scenes and gives you a browser URL.

1. Ask for a reviewable HTML document

Use a natural request in your agent session:

Create a reviewable design doc in HTML

or:

Render this as a visual HTML report

The agent creates the document, validates it, starts a session-scoped preview, and returns a URL.

2. Review in the browser

Open the preview URL. Select text or images, add comments where the issue appears, and keep the review context inside the document instead of scattering it across chat messages.

3. Let the agent answer comments

When comments are added, the agent can read them, classify what needs action or clarification, and then write substantive replies into the same browser threads with add-reply. You can read the agent reply beside the original selected text.

4. Resolve threads to trigger updates

If the agent needs clarification, answer in the thread. When the thread is resolved, the agent can apply the agreed document changes, re-render the HTML, and show a browser notification so you can reload when ready.

5. Preview plans before implementation

For implementation plans, ask for a visual plan preview:

Preview this plan as HTML

The plan text can include a temporary Plan preview: URL. The preview preserves the full proposed plan text and adds supplemental sections for phases, dependencies, review context, and test coverage that are hard to inspect in CLI text.

Language behavior

The skills are bilingual. If you ask in English, the agent should use English for progress updates, preview handoff text, review replies, and final responses. If you ask in Japanese, it should use Japanese. Source material and quoted text are not translated unless you explicitly ask for translation.

Skills

Agent / Developer CLI Reference

These commands are the internal interface used by the skills and by plugin developers. End users normally interact through Claude Code or Codex prompts and browser review.

All commands are exposed through:

python3 -m scripts.html_review_workbench.cli <command>

Schemas

The workbench is schema-driven:

• schemas/document-model.schema.json
• schemas/comments.schema.json
• schemas/preview-session.schema.json

These schemas define the rendered document model, persisted review comments, and preview session metadata.

Development

Requirements:

• Python 3.11+
• No P