lavish-axi

For when a rich editor is not rich enough.

HTML is the new markdown. Lavish is the new editor for your HTML artifacts.

Agents are good at producing rich HTML artifacts, but the human-agent collaboration loop on such artifacts is lacking and falls back into screenshots and long responses for “tell me what to change.” That loses the thing HTML is best at: interactivity.

Lavish Editor opens agent-generated HTML files in a local browser, lets you pinpoint elements and selected text, edit rendered Mermaid diagrams as whiteboards, and send feedback to the agent to address.

• Local-first - Review local HTML artifacts with a local CLI and no cloud dependency in the core feedback loop; hosted sharing through third-party ht-ml.app is explicit and opt-in.
• Human-AI collaboration - Annotate elements and selected text ranges, edit Mermaid diagrams as whiteboards, and send messages to the agent without leaving Lavish Editor.
• Battery included - Lavish Editor teaches your agent good visualization for common use cases such as product or technical plans, design explorations and more out of the box.

Lavish Editor is an AXI, which means -

• It's just a CLI any capable agent can run without setup.
• It's optimized for agent ergonomics. TOON output, long polling, and contextual disclosure making it highly token efficient.
• The skill and hooks below only handle discovery; agents learn to use the AXI by using it.

Quick Start

Install the Lavish skill in the Agent Skills format with npx skills:

npx skills add kunchenguid/lavish-axi --skill lavish

That is the entire setup - no npm install needed. The skill teaches your agent to run Lavish through npx -y lavish-axi, so the CLI comes along on demand. In restricted subprocess sandboxes, CI, or agent harnesses where npx -y exits opaquely, the skill also documents direct installed-copy fallbacks through the local or global npm install path. Its frontmatter also includes Hermes Agent metadata, so Hermes-compatible harnesses can categorize and surface it as a first-class productivity skill. This installs the public lavish skill. The repository also contains an internal lavish-design brand skill for maintainers; default npx skills add ... --list and skills.sh discovery hide it unless INSTALL_INTERNAL_SKILLS=1 is set.

Then, in agents that expose skills as slash commands (Claude Code, for example), invoke it directly:

/lavish let's discuss our plan here

Or just ask for anything that is easier to grasp visually - a plan, comparison, diagram, table, code view, or report - and the agent loads the skill on its own when it recognizes the task.

By default the skill lands in the current project's skills directory (.claude/skills/, for example); add -g to install it for all projects (~/.claude/skills/).

Other Ways to Use Lavish

The skill is the recommended path, but it is not the only one.

Zero setup

Lavish is an AXI, so any capable agent can run the CLI directly with nothing installed at all. Just tell your agent:

Use `npx -y lavish-axi` to write a product or technical plan for what we discussed.

Session hook

Want Lavish's ambient context - including your live open sessions - fed into every agent session instead of loading on demand? Install the CLI globally and opt into the hook:

npm install -g lavish-axi
lavish-axi setup hooks

This installs a SessionStart hook for Claude Code, Codex, OpenCode, and GitHub Copilot CLI that surfaces open sessions, visualization playbooks, and usage guidance at the start of each session. Unlike the skill, the hook also shows your live open sessions, so a fresh agent session can resume an in-flight review. Restart your agent session after running this so the new hook takes effect.

Agent Plugin

Lavish also ships as an Agent Plugin - the vendor-neutral packaging standard for skills and MCP servers - so clients that speak that format can load it directly.

No marketplace is involved. The installed npm package is the plugin: plugin.json sits at the package root next to the skills/ directory, so whatever npm install already put on disk is a complete, conformant plugin. Install the CLI, then register it:

npm install -g lavish-axi
lavish-axi setup plugin

That registers the installed package with every supported client it finds - VS Code, Cursor, and GitHub Copilot CLI - and reports which ones were absent. It is opt-in and idempotent, and it repairs the registered path after a reinstall or relocation. Reload each client afterward.

Each client is registered independently: one that cannot be registered is reported with what to do about it, and never blocks the others or fails the command.

To register by hand instead, point any client at the package directory (npm root -g/lavish-axi):

Codex and ChatGPT install plugins only from marketplace sources, so Codex users should use the session hook above instead. Lavish declares no MCP server - the CLI itself is the agent interface - so a plugin install brings the same lavish skill, and the skill and plugin are alternatives rather than a stack.

From source

git clone https://github.com/kunchenguid/lavish-axi.git
cd lavish-axi
pnpm install --frozen-lockfile
pnpm run build
pnpm link

How It Works

┌───────────────┐
│ Agent writes  │
│ artifact.html │
└───────┬───────┘
        ▼
┌────────────────────────┐
│ lavish-axi <file_path> │
│ opens local browser UI │
└───────┬────────────────┘
        ▼
┌────────────────────────┐
│ Human annotates text   │
│ or elements, sends     │
│ chat, or queues layout │
│ issues from the inbox  │
└───────┬────────────────┘
        ▼
┌────────────────────────┐
│ lavish-axi poll waits  │
│ and returns prompts    │
│ the user queued        │
└────────────────────────┘

• File-path identity - Sessions are keyed by the canonical HTML file path, so agents do not need opaque IDs.
• Portable artifacts - The artifact runs in an iframe while Lavish injects a small SDK for annotations, snapshots, feedback controls, and render-time layout checks. Lavish does not inject any design system, so the saved HTML file renders identically whether you open it through lavish-axi or directly in a browser. Run lavish-axi design for the single source of agent-facing design guidance and optional CDN or Mermaid snippets.
• Self-paint warning - lavish-axi <html-file>, export, and share run a render-free check for artifacts missing an explicit page background and return a one-line self_paint_warning. The check fails open - any stylesheet link, @import, Tailwind runtime script, color-scheme, or html/body/:root background signal suppresses it - and it never blocks the open.
• Open-time layout gate - The browser chrome masks an artifact only while the real in-iframe audit waits for fonts and final geometry. The first completed check always reveals the artifact, whatever it found; the gate never holds the review hostage waiting for a repair. The user can click Show anyway, and a bounded safety timeout fails open when no check has completed.
• Layout issues inbox - Detection is passive. After fonts and finite animations settle, the injected SDK confirms severe failures from direct rendered evidence such as materially escaped meaningful content or required controls, clipped text fragments, viewport reachability, or near-total semantic occlusion. Explicit ellipsis and line clamp, standard visually hidden accessibility text, intentional scrollers or masks, parent overhang, generic element scroll geometry, decorative overlap, and uncertain motion do not produce findings by themselves. Proven failures are filed in a Layout issues button in the top bar, which is hidden while nothing is unresolved and otherwise shows the unresolved count. Its drawer lists each issue with severity, a plain-language explanation, the affected viewport, the target/component identity, when it was last seen, and its lifecycle state, plus per-issue Reveal (highlight it in the artifact) and Dismiss actions. Nothing is selected by default. The user picks issues (or Select all) and Queue selected fixes turns that whole group into one ordinary queued prompt, tagged layout-warnings, that reaches the agent through the normal feedback path when they send. Detection never returns lavish-axi poll and never wakes an agent; only the user queueing a fix does. The one exception is a fatal artifact_failures response, for failures that make the review itself unusable, such as the artifact document or one of its own local assets failing to load.
• Layout issue lifecycle - Each issue is identified by a stable fingerprint of the diagnostic rule, the normalized target identity, and the viewport class, so repeat detections update one record instead of inflating the count. Open means the latest completed check for its viewport still detects it. Queued for fix means the user asked for a repair - it stays unresolved and counted, and cannot be queued again while that request is outstanding. Resolved requires a newer successful artifact load plus a complete check at the same viewport that no longer detects it; it then leaves the count but keeps a bounded history. Still present (recurring) means a queued issue survived a newer revision, so it is selectable again with its earlier attempt retained. Unverified means a reload or check failed or was incomplete, so the prior issue was preserved rather than cleared. Returned means a resolved issue came back on a later revision. Dismissal applies only to the current artifact revision; a later revision surfaces the issue again if it is still detected. A check at one viewport never clears an issue found at another, and a viewport removed from the configured diagnostic set (LAVISH_AXI_DIAGNOSTIC_VIEWPORTS, default all) is marked obsolete with an explicit reason rather than reading as fixed.
• Local assets - Copy local images, CSS, fonts, and scripts next to the HTML artifact and reference them with relative paths from that directory; root-prefixed paths such as /assets/logo.png will not resolve through Lavish's artifact route.
• Export and sharing - lavish-axi export writes <name>.export.html by inlining local assets only, stripping the annotation SDK, and leaving remote CDN/font references as links that still need network access. lavish-axi share publishes the same local-inlined HTML to ht-ml.app, a third-party hosting service not part of Lavish. Publishing sends the artifact to ht-ml.app's servers, public by default, or private and password-protected with --password; the response includes a secret update_key shown once for later management. Bundling never fetches remote URLs, Lavish itself does not set a CSP, local reads stay confined and size-capped, and absolute file:// paths outside safe inlined asset references are redacted before output. Per-asset and per-bundle inline caps default to 10 MB and 25 MB, overridable with LAVISH_AXI_EXPORT_MAX_ASSET_BYTES and LAVISH_AXI_EXPORT_MAX_BUNDLE_BYTES. Unresolved local assets or export notices such as author-set CSP meta tags and redacted file URLs are surfaced in command or browser output. Use --token or LAVISH_AXI_HTML_APP_TOKEN for an optional bearer token; set LAVISH_AXI_HTML_APP_API_URL only when overriding the ht-ml.app API base.
• Live reload - Lavish watches the HTML artifact file by default and preserves review context across reloads: the artifact iframe scroll position, an open annotation card's unsent text, and answers to data-lavish-question controls (application-owned form state is left alone). While a queued layout-issue batch is outstanding, closely spaced saves coalesce so one batch of fixes costs one refresh. To also reload on sibling asset changes, add data-lavish-live-reload-root to the root element or <meta name="lavish-live-reload" content="root">.
• Feedback controls - Native controls (radios, checkboxes, inputs, selects, buttons, labels, disclosure summaries, contenteditable) are interactive automatically, so they do not need data-lavish-action. For reversible choices, let option clicks update local state, then queue exactly one final answer from a per-question submit or Queue answer button with window.lavish.queuePrompt(). Mark only custom (non-native) clickable elements with data-lavish-action so Lavish does not annotate them, and use data-lavish-question or queueKey when pre-send updates for the same question should replace each other. Queued annotation preview pills and chat history share a scrollable Conversation panel above a sticky composer, so long feedback queues do not push the text box or send controls off screen. The browser chrome keeps editing actions in the overflow menu (copy path, reload artifact, copy DOM snapshot, export standalone HTML, publish link, end session), while the composer exposes Send & End beside Send to Agent to submit queued prompts and user-ended attribution together.
• Keyboard shortcuts - In the chrome composer, Enter sends queued prompts and Shift+Enter inserts a newline. In the annotation card, Enter queues the annotation, Shift+Enter inserts a newline, and Ctrl+Enter (Cmd+Enter on macOS) queues it and sends all queued prompts immediately. Cmd+I or Ctrl+I toggles between annotate and explore mode from either the browser chrome or the artifact iframe, including while focus is in a textarea or control.
• Agent presence - The browser shows when no agent is listening, keeps queued feedback for the next successful lavish-axi poll send even across reloads, and only blocks human sends while the agent is working on delivered feedback; the agent's reply (--agent-reply) concludes that work and re-enables sends. The no-timeout poll always writes an immediate stderr banner so it is visibly not hung; it adds the periodic stderr wait ticks only in an interactive terminal, so when stderr is piped (as under agent harnesses) the captured output carries no tick noise. Stdout always stays reserved for the final response; if the poll is interrupted or times out, re-run it because queued feedback is never lost. Codex-specific guidance keeps that poll attached to the active turn instead of hiding it in a background task, because completed background tasks may not resume the agent.
• Session end etiquette - Lavish tracks who ended a session: a human clicking End session (or Send & end session) in the browser is a user-initiated end, while lavish-axi end <html-file> is agent-initiated. A plain lavish-axi <html-file> after a user-initiated end refuses to reopen the browser and returns guidance instead; pass --reopen only when the user asks for further review or something important needs their visual attention. Agent-initiated ends keep reopening normally, same as before. lavish-axi poll's ended response and the feedback response for the final batch before an end both carry next_step guidance telling the agent to stop polling and deliver remaining updates in chat instead of reopening.
• Precise targets - Text annotations include selected text plus range anchors, so agents are not limited to whole-element selectors.
• Mermaid diagrams - In the Lavish browser, every rendered Mermaid diagram in a .mermaid container becomes an embedded editable Excalidraw whiteboard. Click a diagram to unlock editing, and use its Fullscreen action to edit it over the whole viewport. Whiteboard scenes autosave locally. If a live reload changes the Mermaid source, the whiteboard shows that its edits are stale; reopening it lets the reviewer re-convert and discard the saved edits or keep editing the saved scene. Use Queue feedback to add a bounded edit summary plus local .excalidraw scene and PNG preview paths to the Conversation panel, then click Send to Agent to deliver it. The agent updates the artifact's Mermaid source, which remains authoritative. Flowchart, sequence, class, ER, and state diagrams convert to editable shapes; other diagram types are images that reviewers can draw and annotate. Lavish changes only the browser view, so saved, standalone, and exported artifacts still render plain Mermaid.
• Server cleanup - The detached server stops after the last session ends when nothing is connected, or after LAVISH_AXI_IDLE_TIMEOUT_MS (default 30 minutes) with no browser or poll connections. Set LAVISH_AXI_IDLE_TIMEOUT_MS=0 or off to disable idle self-shutdown.
• Local-first state - Session state stays under ~/.lavish-axi/ by default, or LAVISH_AXI_STATE_DIR when set.
• Diagnostic viewports - LAVISH_AXI_DIAGNOSTIC_VIEWPORTS sets which viewport classes the layout-issue inbox tracks (mobile, compact, desktop; comma-separated, default all). Warnings whose class leaves the set are marked obsolete with an explicit reason instead of silently reading as fixed.
• Server port - Set LAVISH_AXI_PORT to choose the server port; it defaults to 4387.
• Network binding - The server binds to loopback (127.0.0.1) by default. Set LAVISH_AXI_HOST to bind elsewhere; a wildcard (0.0.0.0 or ::) binds every interface. Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to anything that can reach it, so only do so on a trusted network. Set LAVISH_AXI_LINK_HOST to control the hostname written into generated session links (defaults to the bind address, or loopback when bound to a wildcard).
• Allowed hosts - To defend against DNS rebinding, the server rejects (403) any request whose Host header is missing or not one it answers to: the loopback names (127.0.0.1, ::1, localhost) plus the configured bind and link host. If you reach the server under another name - a wildcard bind accessed by LAN IP, a reverse-proxy hostname, or an extra interface - list those names in LAVISH_AXI_ALLOWED_HOSTS (whitespace-separated) to allow them. Behind a reverse proxy, the forwarded X-Forwarded-Host is validated against the same list, so add your public hostname there and have the proxy send it together with X-Forwarded-Proto. Set LAVISH_AXI_ALLOWED_HOSTS to * to disable the check entirely (only when the server sits behind your own authentication or proxy).
• Browser opening - Set LAVISH_AXI_NO_OPEN=1, equivalent to --no-open, to create or resume a session without launching a browser window.

CLI Reference

Known playbook IDs: diagram, table, comparison, plan, code, input, slides. One artifact often combines several playbooks, such as a plan that includes a comparison and a diagram, so agents must match against each use_when trigger and open every matching playbook before writing HTML. For flows, architecture, state, or sequence diagrams, open the diagram playbook for the recommended tooling and SVG guidance.

Flags

Development

pnpm run check          # Run all verification commands
pnpm run build          # Bundle the publishable CLI, chrome, and design assets
pnpm run build:skill    # Regenerate the installable lavish skill
pnpm test               # Run node:test tests
pnpm run lint           # Run ESLint
pnpm run format:check   # Check Prettier formatting
pnpm run typecheck      # Run TypeScript checkJs validation