lavish-axi

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 diagrams your agent authored as Mermaid 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 whiteboard diagrams, 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. It stays a short stub and sends the agent to `npx -y lavish-axi --help`, `design`, and `playbook` for current instructions, so an installed copy cannot go stale against a newer CLI. 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: ```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. ### Agent Plugin Lavish also ships as an [Agent Plugin](https://agent-plugins.org) - 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: ```sh 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`): | Client | Register with | | ------------------ | ------------------------------------------------------------------------------------------------------------------ | | VS Code | `"chat.pluginLocations": { "": true }` in user settings | | Cursor | link the package dir at `~/.cursor/plugins/local/lavish-axi` (`setup plugin` handles Windows link compatibility) | | GitHub Copilot CLI | `copilot plugin install ` (or `copilot plugin install kunchenguid/lavish-axi` straight from the repo) | 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 ```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 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 a sandboxed iframe while Lavish injects a small SDK for annotations, snapshots, feedback controls, and render-time layout checks. Author-defined links and popups can open in top-level tabs, while artifact documents remain sandboxed without same-origin access. 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, including optional CDN snippets and the whiteboard (Mermaid) opt-in snippet. - **Self-paint warning** - `lavish-axi `, `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 client-side check reveals the artifact, whatever it found and even if reporting that check to the server fails; the gate never holds the review hostage waiting for a repair or a network round-trip. The user can click **Show anyway**, and a bounded safety timeout fails open from every gate state. If the review cannot load at all - the chrome's own script never runs, or the server does not answer the artifact's load request after several retries - the mask names the problem and offers **Check and reload** without removing the independent **Show anyway** escape. A review already loaded in another browser tab is named the same way, with a **Take over here** button that moves it into the current tab, because Lavish loads an artifact in one tab at a time. - **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 viewpor