htmlify

Turn long agent answers into self-contained HTML artifacts people can scan, discuss, annotate, and ship.

What It Is

htmlify is both:

• a Pi / Oh My Pi extension for exporting long assistant replies as local HTML
• an agentskills.io-compatible skill for asking coding agents to produce useful single-file HTML briefs, maps, reviews, reports, explainers, and lightweight editors

It merges three ideas:

• Long answers should stay visible in the terminal until the user explicitly exports them.
• HTML beats markdown when the work is spatial, comparative, interactive, or meeting-facing.
• Operator artifacts should be evidence-first, visual, self-contained, and production-safe.

Skill Install

This repository root is a valid Agent Skill directory because it contains SKILL.md.

mkdir -p ~/.codex/skills
git clone https://github.com/zakelfassi/htmlify.git ~/.codex/skills/htmlify

For other clients that support the agentskills.io format, install or copy this folder into that client's skills directory. The required skill entrypoint is:

htmlify/SKILL.md

The skill uses progressive disclosure: SKILL.md is the activation surface, and references/htmlify-principles.md is loaded only when deeper artifact guidance is needed.

Coding Agent Integrations

htmlify can be used two ways across coding agents:

• Skill/manual mode: install the folder and invoke htmlify when a response should become a browser-ready artifact.
• Hook/automatic mode: configure the agent to write an HTML artifact when a final answer is longer than a threshold.

Codex local skill install:

mkdir -p ~/.codex/skills
git clone https://github.com/zakelfassi/htmlify.git ~/.codex/skills/htmlify

Claude Code skill install:

mkdir -p ~/.claude/skills
git clone https://github.com/zakelfassi/htmlify.git ~/.claude/skills/htmlify

Claude Code optional Stop hook:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /Users/zakelfassi/.claude/skills/htmlify/hooks/claude-code-stop-htmlify.js",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

The Claude hook reads last_assistant_message from the Stop event and writes an HTML artifact when it is at least HTMLIFY_MIN_CHARS characters. Default threshold is 2500.

For Cursor, Windsurf, Aider, and other agents, point the agent at SKILL.md or use the bundled CLI:

printf '%s' "$LONG_ANSWER_TEXT" | npx @zakelfassi/htmlify htmlify-answer --title "Agent Answer"

See references/agent-integrations.md for project-level rules, hook safety, and per-agent recipes.

Extension Install

Native Pi npm install:

pi install npm:@zakelfassi/htmlify

Native Pi git install:

pi install git:https://github.com/zakelfassi/htmlify.git

Oh My Pi / OMP global install:

mkdir -p ~/.omp/agent/extensions
git clone https://github.com/zakelfassi/htmlify.git ~/.omp/agent/extensions/htmlify

Then ask for a long answer and run:

/htmlify-version
/htmlify local

Legacy command aliases remain available: /html-last, /html-last-version, and /html-comments.

Render Modes

Mode	What it does	Best for
local	Fast local render with a designed shell, outline rail, excerpt hero, and clickable links	Speed and reliability
pi	Uses the current Pi model for a richer second-pass HTML render	Staying in the current session/model context
gemini	Uses Gemini CLI for a richer external render; falls back to local HTML if valid HTML is not returned	Maximum polish when Gemini is available

Commands

Command	Result
/htmlify	Opens quick local HTML without starting a Pi model turn
/htmlify choose	Opens a render-mode chooser
/htmlify local	Forces quick local HTML
/htmlify pi	Forces designed HTML via the current Pi model
/htmlify gemini	Forces designed HTML via Gemini CLI
/htmlify-version	Shows the loaded extension version
/htmlify-comments <comments.json>	Imports downloaded HTML review comments and sends them back to the current agent

Runtime Behavior

• Long answers are detected from message length, line count, or paragraph count.
• Long answers are captured into session state so export commands can work after the answer finishes.
• Local and designed exports open automatically in the browser after the file is written.
• Exports include a trusted local annotation layer: highlight text, add comments, copy Markdown for the agent, or download a comments JSON bundle.
• Rich Pi/Gemini renders must be standalone HTML documents with inline CSS only.
• Rich HTML is validated before writing: scripts, event-handler attributes, javascript: URLs, external assets, external CSS URLs, unsafe tags, oversized output, and overly complex output are rejected or routed to fallback behavior.

Repo Layout

htmlify/
├── .github/workflows/ci.yml
├── assets/
├── bin/
│   └── htmlify-answer.js
├── hooks/
│   └── claude-code-stop-htmlify.js
├── references/
│   ├── agent-integrations.md
│   └── htmlify-principles.md
├── test/
│   └── extension.test.js
├── index.js
├── package.json
├── pnpm-lock.yaml
├── README.md
└── SKILL.md

Development

Use PNPM:

pnpm install
pnpm test

If you modify the runtime, re-test these flows:

• long answer -> answer remains visible; no automatic replacement notice appears
• /htmlify -> local HTML writes and opens without starting a Pi model turn
• /htmlify choose -> chooser appears when supported
• /htmlify pi -> second-pass render path queues/runs and validates rich HTML
• /htmlify gemini -> Gemini render path succeeds or cleanly falls back
• /htmlify-comments <comments.json> -> browser comments validate and queue a structured review prompt
• /htmlify-version -> version shown in-session

Publishing

The unscoped npm name htmlify is already taken. Publish this package under the scoped name:

NPM_CONFIG_CACHE=/private/tmp/htmlify-npm-cache npm publish --access public

Trust And Security

Extensions run with your user permissions. Only install from sources you trust, review the source before installing, and pin a git ref or tag when you need reproducible behavior.

Rich HTML generated by Pi or Gemini is treated as untrusted until it passes validation. The validator is intentionally conservative: if rich output includes active scripts, event handlers, external assets, or unsafe URLs, htmlify falls back to local HTML rather than writing the rich document.