html-skills-listen

html-skills-listen — server-mode setup for html-skills artifacts

System primitive for the html-skills plugin. It runs a bundled script that detects the environment, starts (or finds) this session's local receiver on an ephemeral port, and prints what you need; you then arm a Monitor on the receiver's log so each submit becomes a session notification, and hand the URL back to the skill that invoked you.

Steps

1. Run the setup script with this session's id:

   bash "${CLAUDE_PLUGIN_ROOT}/skills/html-skills-listen/scripts/listen.sh" "${CLAUDE_SESSION_ID}"
   

   Output is KEY=VALUE lines. Always present: SID, LOG, MIDF, STATUS. With STATUS=STARTED or STATUS=ALREADY_RUNNING you also get URL. After a restart of a receiver that had died, STATUS=STARTED also prints RESTARTED=1 and, if its previous port could not be reused, PORT_CHANGED=1.

2. Branch on STATUS:

   • STATUS=WEB — Claude Code web session; the sandbox can't reach the user's browser. Don't arm a Monitor. Tell the parent skill (or the user, if invoked directly):

     ⓘ Claude Code web session detected. Server mode can't work here. The artifact will use clipboard mode automatically — Submit copies JSON to the clipboard for paste-back.

     Stop here.

   • STATUS=ERROR — report the script output (it names the cause: node-not-found, receiver-died-on-startup, no-listening-line-in-log) and stop. The parent skill proceeds in clipboard mode.

   • STATUS=ALREADY_RUNNING — the Monitor was armed when this session's receiver first started; don't arm another. Return URL to the parent skill and stop.

   • STATUS=STARTED — continue to step 3.

3. Arm a persistent Monitor on the receiver's log. Substitute the literal LOG value into the command (the Monitor tool can't expand variables itself):

   Monitor(
     description: "html-skills artifact submissions",
     command: "tail -f <LOG> | grep --line-buffered '\"method\":\"notifications/claude/channel\"'",
     persistent: true,
     timeout_ms: 3600000
   )