{"id":51349739,"url":"https://github.com/u-ichi/reviewable-html-workbench","last_synced_at":"2026-07-02T15:03:18.520Z","repository":{"id":364596987,"uuid":"1241234879","full_name":"u-ichi/reviewable-html-workbench","owner":"u-ichi","description":"Claude Code / Codex CLI plugin for generating reviewable HTML documents with preview, inline review comments, and agent feedback ingestion.","archived":false,"fork":false,"pushed_at":"2026-06-22T10:57:35.000Z","size":1211,"stargazers_count":158,"open_issues_count":1,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T12:26:48.659Z","etag":null,"topics":["claude-code","codex-cli","html-review","plugin","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/u-ichi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-17T05:56:17.000Z","updated_at":"2026-06-22T10:57:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/u-ichi/reviewable-html-workbench","commit_stats":null,"previous_names":["u-ichi/reviewable-html-workbench"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/u-ichi/reviewable-html-workbench","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-ichi%2Freviewable-html-workbench","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-ichi%2Freviewable-html-workbench/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-ichi%2Freviewable-html-workbench/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-ichi%2Freviewable-html-workbench/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/u-ichi","download_url":"https://codeload.github.com/u-ichi/reviewable-html-workbench/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-ichi%2Freviewable-html-workbench/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35051912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex-cli","html-review","plugin","python"],"created_at":"2026-07-02T15:03:13.681Z","updated_at":"2026-07-02T15:03:18.508Z","avatar_url":"https://github.com/u-ichi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reviewable HTML Workbench\n\n[![Test](https://github.com/u-ichi/reviewable-html-workbench/actions/workflows/test.yml/badge.svg)](https://github.com/u-ichi/reviewable-html-workbench/actions/workflows/test.yml)\n![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)\n![License: MIT](https://img.shields.io/badge/license-MIT-green)\n\nA 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.\n\n![Overview](docs/images/overview.png)\n\n## Overview\n\nAgent 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.\n\nReviewable HTML Workbench solves this by putting the review conversation **inside the document itself**:\n\n1. **Generate** — The agent produces an HTML bundle with structured sections, diagrams, and images.\n2. **Review** — You open the preview, select any text or image, and leave a comment right where the issue is.\n3. **Ingest** — The agent reads your comments, classifies each one, and writes replies explaining what it will change.\n4. **Improve** — The agent updates the document, re-renders, and you see the changes in context.\n5. **Repeat** — Keep commenting and refining until the document is ready.\n\nComments 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.\n\nThe 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.\n\n## Features\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **Review Ingestion**: comments are classified as actionable, clarification, already addressed, and related states so the review conversation stays structured across iterations.\n- **Publish \u0026 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.\n- **Document Model**: schema-driven document input for predictable HTML generation.\n- **HTML Rendering**: produces `index.html`, copied assets, and `renderer-manifest.json`.\n- **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.\n- **Dark/Light Theme**: UI support for theme switching in rendered review documents.\n- **Diagram + Image Support**: stores Mermaid sources, renders fallback diagrams, and attaches generated image assets to document model blocks.\n\n## Installation\n\n### Claude Code\n\nAdd the GitHub repository as a plugin marketplace and install:\n\n```bash\nclaude plugin marketplace add u-ichi/reviewable-html-workbench\nclaude plugin install reviewable-html-workbench\n```\n\nAlternatively, clone the repository and install locally:\n\n```bash\ngit clone https://github.com/u-ichi/reviewable-html-workbench.git\ncd reviewable-html-workbench\nclaude plugins install .\n```\n\nFor local development, run Claude Code with this plugin directory:\n\n```bash\nclaude --plugin-dir /path/to/reviewable-html-workbench\n```\n\n### Codex CLI\n\nAdd the GitHub repository as a plugin marketplace, then add the plugin. This\nrepository's marketplace name is `reviewable-html-workbench-local`:\n\n```bash\ncodex plugin marketplace add u-ichi/reviewable-html-workbench\ncodex plugin add reviewable-html-workbench@reviewable-html-workbench-local\n```\n\nTo verify the configured marketplace name, check the left column:\n\n```bash\ncodex plugin marketplace list\n```\n\nOr clone and register locally:\n\n```bash\ngit clone https://github.com/u-ichi/reviewable-html-workbench.git\ncodex plugin marketplace add ./reviewable-html-workbench\ncodex plugin add reviewable-html-workbench@reviewable-html-workbench-local\n```\n\nCodex 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.\n\n## Quick Start\n\nYou 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.\n\n### 1. Ask for a reviewable HTML document\n\nUse a natural request in your agent session:\n\n```text\nCreate a reviewable design doc in HTML\n```\n\nor:\n\n```text\nRender this as a visual HTML report\n```\n\nThe agent creates the document, validates it, starts a session-scoped preview, and returns a URL.\n\n### 2. Review in the browser\n\nOpen 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.\n\n### 3. Let the agent answer comments\n\nWhen 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.\n\n### 4. Resolve threads to trigger updates\n\nIf 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.\n\n### 5. Preview plans before implementation\n\nFor implementation plans, ask for a visual plan preview:\n\n```text\nPreview this plan as HTML\n```\n\nThe 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.\n\n### Language behavior\n\nThe 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.\n\n## Skills\n\n| Skill | Purpose | Trigger examples |\n|---|---|---|\n| `visual-html-renderer` | Turn content into a polished, reviewable HTML preview with diagrams, images, comments, and publish/download controls. | `visual HTML renderer`, `render this as HTML`, `turn this into HTML`, `create an HTML preview`, `generate a visual HTML report`, `make this a reviewable HTML document`, `diagrammed HTML report` |\n| `reviewable-design-doc` | Create a review-ready design document, watch browser comments, reply in-thread, and apply resolved feedback. | `design doc`, `reviewable design doc`, `create a reviewable design doc`, `make a design doc in HTML`, `build a review-ready design document`, `ingest review comments`, `process review comments`, `reply to review comments`, `apply resolved comments` |\n| `plan-preview` | Add a temporary Reviewable HTML Workbench preview URL that preserves the full proposed plan and adds supplemental visual context before implementation starts. | `graphical plan review`, `graphical plan preview`, `preview this plan as HTML`, `show this plan visually`, `add a plan preview URL`, `preview the proposed plan`, `この計画をHTMLでプレビューして`, `計画をHTMLで確認したい` |\n\n## Agent / Developer CLI Reference\n\nThese 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.\n\nAll commands are exposed through:\n\n```bash\npython3 -m scripts.html_review_workbench.cli \u003ccommand\u003e\n```\n\n| Command | Description |\n|---|---|\n| `build-model` | Build a document model from natural content. |\n| `render` | Generate an HTML bundle from a document model. |\n| `check-model` | Check whether a document model is ready for final HTML rendering. |\n| `attach-image` | Attach a generated image asset to an image-capable block in a document model. |\n| `preview` | Start or describe a session-scoped preview runtime. |\n| `plan-preview` | Create an ephemeral HTML preview for a proposed plan. |\n| `plan-preview-stop` | Stop and clean up an ephemeral plan preview. |\n| `ingest-review` | Read review comments, classify them, and save review-cycle state. |\n| `validate` | Validate a generated HTML bundle. |\n| `add-reply` | Add an agent reply to a comment thread in `comments.json`. |\n| `check-gates` | Check whether unresolved clarification threads block document updates. |\n| `watch-comments` | Stream browser comment change events from a running preview. |\n| `notify-update` | Notify the browser that the document has been updated. |\n\n## Schemas\n\nThe workbench is schema-driven:\n\n- `schemas/document-model.schema.json`\n- `schemas/comments.schema.json`\n- `schemas/preview-session.schema.json`\n\nThese schemas define the rendered document model, persisted review comments, and preview session metadata.\n\n## Development\n\nRequirements:\n\n- Python 3.11+\n- No Python package dependencies for the core runtime\n- Standard library tests with `unittest`\n\nRun tests:\n\n```bash\nPYTHONPYCACHEPREFIX=\"$PWD/tmp/python-pycache\" python3 -m unittest discover -s tests\n```\n\nValidate plugin manifests:\n\n```bash\npython3 -m json.tool .claude-plugin/plugin.json \u003e/dev/null\npython3 -m json.tool .codex-plugin/plugin.json \u003e/dev/null\n```\n\nValidate the Claude Code plugin manifest:\n\n```bash\nclaude plugins validate .\n```\n\nCheck the CLI entrypoint:\n\n```bash\npython3 -m scripts.html_review_workbench.cli --help\n```\n\n## License\n\nMIT\n\n\u003cdetails\u003e\n\u003csummary\u003e日本語\u003c/summary\u003e\n\nReviewable HTML Workbench は、Claude Code / Codex CLI 向けの HTML レビュー用プラグインです。agent が生成した設計資料・調査レポート・比較表を HTML で出力し、本文の任意の箇所にレビューコメントを書き込めます。agent はそのコメントを読み取り、返信し、内容を改善して再出力します。コメントと改善を繰り返して、ドキュメントを一緒に磨き上げるワークフローを実現します。\n\n完成したら、レビュー要素を除いた読者向けの HTML を 1 ファイルでダウンロードできます（CSS・画像埋め込み済み、OS テーマ自動検知対応）。\n\n英語と日本語の両方の依頼に対応します。英語で依頼した場合は進捗、preview案内、レビューコメントへの返信、最終応答も英語に追従します。日本語で依頼した場合は日本語で返します。元資料や引用は、明示的に翻訳を依頼しない限り翻訳しません。\n\n3つの skill を含みます。\n\n- `visual-html-renderer`: HTML生成、図示、Preview Runtime、bundle検証。\n- `reviewable-design-doc`: レビュー可能な設計資料作成、コメント自動検知、agent返信、解決後の設計反映。\n- `plan-preview`: Plan Mode の計画本文に一時HTMLプレビューURLを追加。\n\n## 日本語での使い方\n\n通常は Python コマンドを直接実行せず、Claude Code や Codex CLI のチャットで自然に依頼します。agent が HTML bundle を生成し、検証し、ブラウザで開ける preview URL を返します。\n\n### 1. レビュー可能な HTML を作る\n\n設計資料をレビュー用 HTML として作りたい場合:\n\n```text\n設計資料をレビュー可能なHTMLで作って\n```\n\n```text\nレビュー可能な設計資料\n```\n\n```text\n設計資料をHTMLで\n```\n\n調査結果や比較表を図示つき HTML にしたい場合:\n\n```text\nこの調査結果を図示つきHTMLでプレビューして\n```\n\n```text\nhtml出力して\n```\n\n```text\nHTMLにして\n```\n\n```text\nHTMLで出して\n```\n\n```text\nHTMLでプレビューして\n```\n\n```text\n図示つきHTML\n```\n\n### 2. ブラウザでレビューする\n\nagent が返した preview URL をブラウザで開きます。本文や画像を選択して、修正してほしい箇所にコメントします。チャットではなく HTML 上にコメントを残すことで、指摘箇所と文脈が失われません。\n\n### 3. コメントを agent に確認・返信させる\n\nコメントを入れ終わったら、次のように依頼します。\n\n```text\nレビュー終わったので確認して\n```\n\n```text\nコメントを反映して\n```\n\nagent はコメント本文と選択範囲を読み、回答・受領・確認依頼が必要なコメントには `add-reply` で同じ HTML コメントスレッドへ返信します。チャットだけで回答して終わるのではなく、ブラウザ上のコメントと回答が対応する形で残ります。解決済みになった指摘は、document model に反映して再 render します。\n\n### 4. 実装前に計画を HTML で確認する\n\n計画の段階、依存関係、検証範囲を視覚的に確認したい場合:\n\n```text\nこの計画をHTMLでプレビューして\n```\n\n```text\n計画をHTMLで確認したい\n```\n\n```text\nplanをグラフィカルに見たい\n```\n\n```text\nplanを図で確認したい\n```\n\n```text\nproposed_planをプレビューして\n```\n\n```text\n計画URLを入れて\n```\n\n計画本文には一時的な `Plan preview:` URL が入り、元の計画本文を全文表示したうえで、CLI本文だけでは読み取りにくいフェーズ、依存関係、判断材料、検証観点を補助表示できます。\n\n### 5. 日本語依頼時の言語方針\n\n日本語で依頼した場合、進捗、preview 案内、レビューコメントへの返信、最終応答は日本語になります。元資料や引用は、明示的に翻訳を依頼しない限り翻訳しません。\n\n### 6. インストール\n\n```bash\n# Claude Code（GitHub から直接）\nclaude plugin marketplace add u-ichi/reviewable-html-workbench\nclaude plugin install reviewable-html-workbench\n\n# Codex CLI（GitHub から直接）\ncodex plugin marketplace add u-ichi/reviewable-html-workbench\ncodex plugin add reviewable-html-workbench@reviewable-html-workbench-local\n```\n\nCodex CLI で marketplace 名を確認したい場合は `codex plugin marketplace list` の左列を見ます。\n\nCodex CLI は plugin 全体を導入する形で、現行の公開操作では言語だけを選んでインストールする方式ではありません。この plugin は同じ runtime に英語・日本語の skill 文書を同梱します。\n\nテストは次のコマンドで実行します。\n\n```bash\nPYTHONPYCACHEPREFIX=\"$PWD/tmp/python-pycache\" python3 -m unittest discover -s tests\n```\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu-ichi%2Freviewable-html-workbench","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fu-ichi%2Freviewable-html-workbench","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu-ichi%2Freviewable-html-workbench/lists"}