lavish-axi

For when a rich editor is not rich enough.

Lavish Editor demo

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 or selected text and send feedback to the agent to address. - **Local only** - Work with your local HTML artifacts with a local CLI. Zero cloud dependency. - **Human-AI collaboration** - Annotate elements, selected text ranges, 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](https://axi.md), 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](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills): ```sh 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. Its frontmatter also includes Hermes Agent metadata, so Hermes-compatible harnesses can categorize and surface it as a first-class productivity skill. 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 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: ```sh 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. ### From source ```sh 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 │ │ opens local browser UI │ └───────┬────────────────┘ ▼ ┌────────────────────────┐ │ Human annotates text │ │ or elements, sends │ │ chat, or browser audit │ │ reports layout issues │ └───────┬────────────────┘ ▼ ┌────────────────────────┐ │ lavish-axi poll waits │ │ and returns prompts │ └────────────────────────┘ ``` - **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. Before writing HTML, choose a design system in strict priority order: follow a user-requested look first; otherwise inspect the project the artifact is about - the subject or product whose content or UI it represents, which may differ from your current working directory - and match that project's Tailwind or theme config, CSS variables or design tokens, component library, brand assets, or existing styled pages. If the artifact previews, proposes, or mocks a specific app's UI, render it in that app's own design system so it faithfully shows the product, even when you are running in a different repo. Only when both come up empty, run `lavish-axi design` for a copy-pasteable Tailwind CSS v4 + DaisyUI v5 CDN fallback, a content-to-playbook router, and Mermaid diagram tooling. That fallback guidance recommends DaisyUI's `luxury` theme by default, warns not to `@apply` DaisyUI classes inside Tailwind browser-runtime style blocks, includes an optional layout safety CSS snippet for dense nested grid/flex layouts, and provides a pinned Mermaid CDN snippet with initialization for flows, architecture, state, and sequence diagrams. - **Open-time layout gate** - The browser chrome masks each artifact until the real in-iframe layout audit reports no error-severity findings. Warning-only artifacts reveal normally; error findings notify the agent through the same `layout_warnings` poll path and keep the curtain up until a clean reload. The user can click **Show anyway**, and a bounded safety timeout reveals with a persistent layout-issues banner so review is never blocked indefinitely. - **Layout warnings** - After fonts load and layout settles, the injected SDK audits the real browser render for page horizontal overflow, element overflow, clipped text, and overlapping text. Intentional horizontal scrollers using `overflow-x: auto` or `scroll` are excluded. Fresh warnings are returned from `lavish-axi poll` as `layout_warnings` with `selector`, `kind`, `overflowPx`, `viewportWidth`, and `severity`, so agents can fix unreadable layouts before asking the human to review. - **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. - **Live reload** - Lavish watches the HTML artifact file by default and preserves the artifact iframe scroll position across reloads. To also reload on sibling asset changes, add `data-lavish-live-reload-root` to the root element or ``. - **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. The browser chrome keeps editing actions in the overflow menu (copy path, reload artifact, copy DOM snapshot, end session) and can submit queued prompts with **Send & end session**, which delivers the prompts before ending the session. - **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. - **Agent presence** - The browser shows when no agent is listening, keeps queued feedback and fresh layout warnings 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 no-timeout poll writes an immediate stderr banner and periodic stderr heartbeats while stdout stays reserved for the final response; if the poll is interrupted or times out, re-run it because queued feedback is never lost. - **Precise targets** - Text annotations include selected text plus range anchors, so agents are not limited to whole-element selectors. - **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/` in the workspace. - **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). ## CLI Reference | Command | Description | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lavish-axi` | Show current sessions and usage guidance. | | `lavish-axi update` | Check for or apply the latest npm release through the AXI SDK self-updater. | | `lavish-axi ` | Open or resume a Lavish Editor session, with the open-time layout gate enabled by default. | | `lavish-axi poll ` | Long-poll until the user sends feedback, ends the session, or the browser reports fresh `layout_warnings`; leave no-timeout polls running, or re-run them if interrupted. | | `lavish-axi end ` | End a session. | | `lavish-axi stop` | Shut down the background server. | | `lavish-axi playbook [id]` | List focused artifact guidance or show one playbook; agents must open each matching playbook before writing HTML. | | `lavish-axi design` | Show the Tailwind + DaisyUI CDN fallback, content-to-playbook router, Mermaid diagram tooling, `luxury` default theme, DaisyUI `@apply` warning, and layout safety snippet. | | `lavish-axi setup hooks` | Install or repair optional SessionStart hooks for Claude Code, Codex, OpenCode, and GitHub Copilot CLI; restart the agent session afterward. | | `lavish-axi server` | Run the local Lavish Editor server. | 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 and use the Mermaid tooling from `lavish-axi design` unless SVG is needed for richly annotated nodes; avoid hand-built div/flexbox boxes-and-arrows. ### Flags | Command | Flag | Description | | ------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lavish-axi ` | `--no-open` | Ensure the server/session exists without opening another browser window. | | `lavish-axi ` | `--no-gate` | Skip the open-time layout curtain for this browser open. | | `lavish-axi update` | `--check` | Report current vs latest npm version without installing an update. | | `lavish-axi poll` | `--agent-reply "..."` | Show the agent's reply in the existing browser chat before polling again. | | `lavish-axi poll` | `--timeout-ms ` | Test/debug escape hatch only; agents should normally omit it and leave the long poll running. | | `lavish-axi stop` | `--port ` | Shut down a server running on a non-default port. | | `lavish-axi server` | `--verbose` | Log session and watcher events to stderr; can also be enabled with `LAVISH_AXI_DEBUG=1`. Detached server output is appended to `~/.lavish-axi/server.log` (or `LAVISH_AXI_STATE_DIR/server.log`) for startup and crash diagnostics. | ## Development ```sh 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 ```

lavish-design

Installation

SKILL.md