Skip to content
Back to search

make-pages-interactive

Turn a directory of static HTML pages into a live commenting surface. Injects a feedback library, starts a tiny server, and routes user comments into a JSONL inbox that the agent watches and responds to by editing the pages. Works in Claude Code and Codex. Trigger phrases — "make this page interactive", "make these pages interactive", "let me comment on this page", "add feedback to these pages", "check feedback", "process pending feedback".

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/paraschopra--make-pages-interactive/badge.svg)](/listings/paraschopra--make-pages-interactive)

HTML

<a href="/listings/paraschopra--make-pages-interactive"><img src="/api/listings/paraschopra--make-pages-interactive/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/paraschopra/make-pages-interactive \
  ~/.claude/skills/make-pages-interactive

That's it. Claude Code auto-discovers any folder under `~/.claude/skills/` that contains a `SKILL.md`.

**Codex:** clone into `~/.codex/skills/make-pages-interactive` instead (or symlink one clone into both). Codex has no file-watch tool, so the skill runs in *wait mode*: it starts the server detached (`scripts/start_server.py`) and blocks on `scripts/wait_for_feedback.py`, handling each batch as it arrives. Keep the Codex session open while you comment; if it stops waiting, say "check feedback".

Updates are explicit:

python ~/.claude/skills/make-pages-interactive/scripts/update.py

Or just say "update the make-pages-interactive skill" in Claude Code.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 141 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: make-pages-interactive
  3. description: Turn a directory of static HTML pages into a live commenting surface. Injects a feedback library, starts a tiny server, and routes user comments into a JSONL inbox that the agent watches and responds to by editing the pages. Works in Claude Code and Codex. Trigger phrases — "make this page interactive", "make these pages interactive", "let me comment on this page", "add feedback to these pages", "check feedback", "process pending feedback".
  4. ---
  5. # Make Pages Interactive
  6. Turns any folder of HTML files into a place the user can leave inline comments on (text selections, element selections, page-level notes). Comments POST to a local JSONL inbox; you (the agent) wait for that inbox, edit the HTML in response, append to `feedback/history.json`, and the page auto-reloads with a walkthrough of what changed.
  7. **Paths:** `<skill>` below means the directory containing this SKILL.md (e.g. `~/.claude/skills/make-pages-interactive` or `~/.codex/skills/make-pages-interactive`). `<dir>` is the folder of HTML pages.
  8. **Pick your mode once, by what your harness offers:**
  9. - **Watch mode** — you can run a command in the background *and* get notified when a file changes (Claude Code: Bash `run_in_background` + the `Monitor` tool).
  10. - **Wait mode** — anything else (Codex, etc.): your shell commands must return, and nothing wakes you between turns. You block on `scripts/wait_for_feedback.py` instead.
  11. ## When to invoke
  12. User says any of:
  13. - "make this page interactive" / "make these pages interactive" → **Setup flow**
  14. - "add feedback to this page" / "let me comment on this page" → **Setup flow**
  15. - "set up feedback on <dir>" → **Setup flow**
  16. - "check feedback" / "process pending feedback" → **Pending check**
  17. - "stop the feedback server" / "kill the server" / "shut it down" → **Stop flow**
  18. - "remove the feedback layer" / "make pages static again" → **Removal flow**
  19. - "update the make-pages-interactive skill" → **Update flow**
  20. ## Setup flow
  21. 1. **Identify the target directory.** Usually the user's current working directory or a folder they named. If ambiguous, ask.
  22. 2. **Inject the feedback tags** into every `*.html` in that directory:
  23. ```
  24. python <skill>/scripts/inject.py <dir>
  25. ```
  26. Add `--recursive` if the pages live in subfolders. Idempotent — safe to re-run. Also creates `<dir>/feedback/inbox.jsonl` and `<dir>/feedback/history.json` if missing.
  27. 3. **Start (or reuse) the server.**
  28. - **Wait mode** (and fine in any harness):
  29. ```
  30. python <skill>/scripts/start_server.py <dir>
  31. ```
  32. It reuses a server already serving `<dir>` on ports 5050–5059, otherwise starts one detached on the first free port, waits until it answers, and prints the URLs. The server survives the command returning and exits by itself after 10 min with no browser open. Log: `<dir>/feedback/server.log`. If it fails because the sandbox blocks binding a local port, re-run it with escalated permissions / approval.
  33. - **Watch mode** (Claude Code): first `curl -s --max-time 2 http://localhost:5050/info`. JSON with `artifact_dir` = `<dir>` → reuse it. JSON for a different dir → try 5051, 5052, …. No response → free. Then run, with `run_in_background: true`:
  34. ```
  35. python <skill>/lib/server.py <dir> --port <chosen>
  36. ```
  37. This one also shuts down when the Claude Code session ends.
  38. 4. **Tell the user the URL(s)**, e.g. `http://localhost:5050/index.html` (use their actual filenames; list the top-level pages if there are several). Pages only work through the server — not opened as files.
  39. 5. **Process anything already pending** (see **Pending check**), then **wait for comments**:
  40. - **Watch mode:** start a `Monitor` on `<dir>/feedback/inbox.jsonl`. Do NOT poll — let the notification arrive, then go to **Responding to feedback**.
  41. - **Wait mode:** loop:
  42. ```
  43. python <skill>/scripts/wait_for_feedback.py <dir> --timeout 300
  44. ```
  45. Give the command a timeout longer than `--timeout` (e.g. 330 s). Exit 0 → it printed `{"pending": [...]}`; handle them (**Responding to feedback**), then run it again. Exit 2 → nothing arrived; run it again. If the command is cut off by your tool timeout, lower `--timeout` and keep looping. After ~30 min with no comments, stop and tell the user: "say *check feedback* when you've left more comments." Keep your messages between iterations to one short line.
  46. ## Responding to feedback
  47. Each comment has a stable `id` (like `c-1730000000000-ab12`), a `type` (`selection`, `elements`, or `page`), the user's `comment` text, and anchor info (selector, `text_snippet`, `outer_html`) pointing at what they commented on. Use `page_url` to find the file.
  48. 1. **(Optional, recommended for anything > a few seconds)** post a status line so the user sees what you're doing:
  49. ```
  50. curl -s -X POST http://localhost:<port>/status -H 'Content-Type: application/json' \
  51. -d '{"comment_id": "<comment id>", "message": "Rewriting the intro (~20s)"}'
  52. ```
  53. `message: null` or `""` clears it. Entries auto-expire after 10 min.
  54. 2. **Edit the HTML** to address each comment. Wrap each modified region with `<span data-cf-change="ch-<short-slug>">…</span>` (or add `data-cf-change` to an existing wrapping element) so the post-reload walkthrough can find it. One anchor per change.
  55. 3. **Append** a batch object to the END of the array in `<dir>/feedback/history.json` (newest = last; the page walks from the end). Write it atomically (write a temp file, then rename) so the polling page never reads half a file:
  56. ```json
  57. {
  58. "batch_id": "b-<timestamp-or-slug>",
  59. "timestamp": "<ISO 8601>",
  60. "comments": [ /* echo back the inbox comments you addressed */ ],
  61. "changes": [
  62. {
  63. "id": "ch-<slug>",
  64. "in_response_to": ["<comment id>"],
  65. "anchor": "ch-<slug>",
  66. "title": "short, concrete",
  67. "description": "longer prose (hidden in UI, just for the record)"
  68. }
  69. ]
  70. }
  71. ```
  72. - `in_response_to` holds the comment's `id` field (the `c-…` value) — that is what marks it processed, both for the page's "processing…" banner and for `wait_for_feedback.py`. A comment you decide not to act on still needs a change entry (say why in `title`), or it will keep coming back as pending.
  73. - `anchor` must match a `data-cf-change` attribute actually present in the HTML.
  74. 4. The page polls `history.json`, auto-reloads (scroll preserved), and offers a walkthrough. The banner clears as soon as any `in_response_to` matches a submitted comment.
  75. 5. Go back to waiting (Monitor notification in watch mode; the `wait_for_feedback.py` loop in wait mode).
  76. ## Pending check
  77. Run on "check feedback", and on setup in a directory that already has a `feedback/` folder:
  78. ```
  79. python <skill>/scripts/wait_for_feedback.py <dir> --once
  80. ```
  81. Exit 0 → unprocessed comments are printed; tell the user the count and process them (in a setup context, ask first if there are many). Exit 2 → nothing pending. Make sure the server is up (`start_server.py` reuses an existing one), then go back to waiting.
  82. ## Stop flow
  83. 1. Identify the port: the one you started, or check `curl -s http://localhost:5050/info` (and 5051, 5052, …) for the one whose `artifact_dir` is `<dir>`.
  84. 2. `lsof -ti:<port> | xargs kill` (the server exits cleanly on SIGTERM; `kill -9` only if the port isn't freed within a few seconds).
  85. 3. Confirm `lsof -i :<port>` is silent. Stop any Monitor / wait loop you had running.
  86. Usually unnecessary: the server exits after 10 min with no browser requests (and, in watch mode, when the agent session ends).
  87. ## Update flow
  88. ```
  89. python <skill>/scripts/update.py
  90. ```
  91. Runs `git pull --ff-only` inside the skill dir if it is a `git clone`. If the skill is vendored into another repo (no `.git` of its own), it says so — update it the way that repo does (e.g. `git subtree pull`).
  92. ## Removal flow (clean static copy)
  93. ```
  94. python <skill>/scripts/inject.py <dir> --remove
  95. ```
  96. Strips both tags from every `*.html`. Leaves `feedback/` alone (delete manually if not wanted).
  97. ## Files in this skill
  98. ```
  99. <skill>/
  100. ├── SKILL.md # this file (agent-facing)
  101. ├── README.md # GitHub-facing docs (human readers)
  102. ├── LICENSE
  103. ├── lib/
  104. │ ├── feedback.js # client library: selection + commenting + tour
  105. │ ├── feedback.css # styles
  106. │ └── server.py # stdlib-only HTTP server
  107. └── scripts/
  108. ├── inject.py # idempotent tag injection / removal
  109. ├── start_server.py # start-or-reuse a detached server (wait mode)
  110. ├── wait_for_feedback.py # block until unprocessed comments exist
  111. └── update.py # git pull --ff-only
  112. ```
  113. ## Gotchas
  114. - The injected `<link>` and `<script>` use absolute paths `/lib/feedback.css` and `/lib/feedback.js`, which `server.py` routes to the skill's own `lib/`. Opening the HTML file directly in a browser silently skips the widget (the page still renders).
  115. - `history.json` order matters: append, don't prepend.
  116. - `anchor` typos cause "anchor not found" warnings after reload.
  117. - The page shows "No agent picked this up yet" if a batch sits unprocessed for 3 min — in wait mode, keep the wait loop running while the user is commenting.
README.md · README · 175 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # make-pages-interactive
  2. A Claude Code / Codex skill that turns any folder of static HTML pages into a **live commenting surface**. Highlight text, click an element, leave a note — the comment lands in a local inbox that Claude reads and responds to by editing the page. The page auto-reloads with a walkthrough of what changed.
  3. Originally built for iterating on research artifacts (long HTML reports with plots, tables, explanations) but works for any folder of HTML: docs, design mocks, generated reports, prototype UIs.
  4. ![Screenshot of make-pages-interactive in action](screenshot.png)
  5. ---
  6. ## How it works
  7. ```
  8. ┌──────────────────┐
  9. user highlights│ feedback.js │ POST /feedback
  10. / clicks ───▶ │ (in every page) │ ───────────────┐
  11. └──────────────────┘ ▼
  12. ┌────────────────┐
  13. ┌──────────────────┐ poll │ server.py │
  14. page reloads ◀─│ feedback.js │ ◀───── │ (stdlib HTTP) │
  15. with walkthru └──────────────────┘history │ │
  16. └───────┬────────┘
  17. │ append
  18. ┌───────────▼────────────┐
  19. │ feedback/inbox.jsonl │
  20. └───────────┬────────────┘
  21. │ Monitor
  22. ▼
  23. ┌────────────────────────┐
  24. │ Claude (the agent) │
  25. │ edits HTML, appends │
  26. │ feedback/history.json │
  27. └────────────────────────┘
  28. ```
  29. The skill is **just three pieces**:
  30. | File | Role |
  31. |------|------|
  32. | `lib/feedback.js` | Client library injected into every page. Handles text selection, element selection, comment editor, page-reload walkthrough. |
  33. | `lib/feedback.css` | Styles for the comment UI. |
  34. | `lib/server.py` | ~250-line stdlib-only HTTP server. Serves the page directory, accepts comment POSTs, serves the lib/ files from `/lib/*`. Auto-shuts-down on parent death or 10 min of idle so it doesn't leak processes. |
  35. Plus glue:
  36. | File | Role |
  37. |------|------|
  38. | `SKILL.md` | What Claude Code reads to know when and how to invoke the skill. |
  39. | `scripts/inject.py` | Idempotently injects (or removes) the two `<link>`/`<script>` tags in every `*.html` in a directory. |
  40. | `scripts/update.py` | `git pull --ff-only` inside the skill directory. |
  41. ---
  42. ## Install
  43. ```bash
  44. git clone https://github.com/paraschopra/make-pages-interactive \
  45. ~/.claude/skills/make-pages-interactive
  46. ```
  47. That's it. Claude Code auto-discovers any folder under `~/.claude/skills/` that contains a `SKILL.md`.
  48. **Codex:** clone into `~/.codex/skills/make-pages-interactive` instead (or symlink one clone into both). Codex has no file-watch tool, so the skill runs in *wait mode*: it starts the server detached (`scripts/start_server.py`) and blocks on `scripts/wait_for_feedback.py`, handling each batch as it arrives. Keep the Codex session open while you comment; if it stops waiting, say "check feedback".
  49. Updates are explicit:
  50. ```bash
  51. python ~/.claude/skills/make-pages-interactive/scripts/update.py
  52. ```
  53. Or just say "update the make-pages-interactive skill" in Claude Code.
  54. ---
  55. ## Usage
  56. Inside any Claude Code session, say:
  57. > "Make these pages interactive."
  58. (or any of: "make this page interactive", "let me comment on this page", "add feedback to these pages")
  59. Claude will:
  60. 1. Inject the feedback library tags into every `*.html` in the current directory.
  61. 2. Create `feedback/inbox.jsonl` and `feedback/history.json`.
  62. 3. Pick a free port (5050 by default, falls back if taken).
  63. 4. Start the server in the background.
  64. 5. Tell you the URL to open.
  65. 6. Start monitoring the inbox so any comment you leave gets picked up immediately.
  66. Open the URL. Comment away. Claude edits the page in response.
  67. ### Removing the feedback layer
  68. To get a clean static copy back (no `/lib/` dependencies in the HTML):
  69. ```bash
  70. python ~/.claude/skills/make-pages-interactive/scripts/inject.py ./your-dir --remove
  71. ```
  72. Or say "remove the feedback layer from these pages."
  73. ---
  74. ## How the server shuts down
  75. The server is designed to never leak — three ways it goes away:
  76. 1. **Parent-process death** *(automatic, ~5–10 s)*. The server records its parent PID at startup and polls every 5 s. When the parent dies (e.g., you close the Claude Code window that launched it), the kernel reparents the server to PID 1 — the watchdog notices and calls `os._exit(0)`. Skipped if the server was started detached at launch (parent was already PID 1, e.g. `nohup`).
  77. 2. **Idle timeout** *(automatic, default 10 min)*. The page polls `/feedback/history.json` every ~4 s, so any open browser tab keeps the server alive. When no client requests have arrived for `--idle-timeout` seconds (default `600`), the server exits. Pass `--idle-timeout 0` to disable.
  78. 3. **Manual stop**. Either:
  79. - Say "stop the feedback server" in your Claude Code session — Claude runs `lsof -ti:5050 | xargs kill` (adjust the port if you used a non-default one).
  80. - Or hit `Ctrl-C` in the terminal where the server is logging.
  81. You generally don't need to think about this. The auto-shutdowns mean abandoned servers self-clean — close your Claude window and within ~10 s the port is free again.
  82. ---
  83. ## Comment types
  84. The library supports three commenting modes:
  85. - **Text selection** — highlight any text, a popup offers "comment on selection".
  86. - **Element selection** — click the "select element" tool, then click an image, table, section. Comment is anchored to a stable selector.
  87. - **Page-level** — a floating button leaves notes that aren't tied to any specific element.
  88. Each comment carries a stable `cf_id`, a selector describing what was pointed at, the comment body, and a timestamp. The library batches comments client-side and submits as a single POST so Claude responds to a coherent set rather than firing on every keystroke.
  89. ---
  90. ## When Claude responds
  91. When you submit a batch:
  92. 1. A "processing…" banner appears at the top of the page.
  93. 2. Your tab title changes to `🔔 …` so you can see progress in a backgrounded tab.
  94. 3. Claude edits the relevant HTML, appends an entry to `feedback/history.json` that maps your comment ids → the changes made.
  95. 4. The page polls `history.json` every ~4 seconds, notices the new entry, and auto-reloads — preserving your scroll position.
  96. 5. Post-reload, a walkthrough appears highlighting each changed region with the title Claude gave it. Press `R` to dismiss; the changes stay in the history sidebar.
  97. ---
  98. ## Repo layout
  99. ```
  100. make-pages-interactive/
  101. ├── SKILL.md # Agent-facing skill spec
  102. ├── README.md # This file
  103. ├── screenshot.png # README screenshot
  104. ├── LICENSE
  105. ├── lib/
  106. │ ├── feedback.js
  107. │ ├── feedback.css
  108. │ └── server.py
  109. └── scripts/
  110. ├── inject.py
  111. └── update.py
  112. ```
  113. ---
  114. ## Why this exists
  115. I kept building long HTML research reports and wanting to leave inline notes on them — "expand this section", "this plot is misleading", "what about edge case X?" — without breaking out of the page to write a separate to-do list. This skill turns that into a one-liner: every page is now a place I can scribble on, and Claude turns the scribbles into edits.
  116. The same workflow works for design docs, generated dashboards, code walkthroughs, anything that lives as HTML.
  117. ---
  118. ## License
  119. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.