# lavish-axi

> A local-first CLI editor for agent-generated HTML artifacts that lets humans annotate elements, send feedback, and collaborate with AI agents in a browser UI.

lavish-axi is an open-source CLI tool built by Kun Chen that bridges the gap between AI-generated HTML artifacts and human review. It opens agent-produced HTML files in a local browser, lets users pinpoint elements or selected text, and sends structured feedback back to the agent — all without leaving the editor. The project is published on npm under the MIT license and has accumulated over 1,200 GitHub stars since its creation in May 2026.

## What It Is

lavish-axi is an **AXI** (Agent eXtensible Interface) — a CLI that any capable AI agent can invoke directly without prior setup. It solves a specific problem in human-AI collaboration: agents are good at producing rich HTML artifacts (plans, comparisons, diagrams, reports), but the feedback loop typically degrades into screenshots and long text descriptions. lavish-axi restores interactivity by letting humans annotate the live rendered artifact and return precise, structured prompts to the agent.

## How the Collaboration Loop Works

The core workflow follows four steps:

- The agent writes an HTML artifact to a local file path.
- `lavish-axi <file_path>` opens a local browser UI with the artifact in an iframe.
- The human annotates text ranges or DOM elements, types feedback, or interacts with native controls.
- `lavish-axi poll` long-polls and returns the human's prompts to the agent, including any layout warnings detected at render time.

Sessions are keyed by canonical file path, so agents never need opaque session IDs. The server binds to loopback by default, keeping the entire feedback loop local with no cloud dependency unless the user explicitly runs `lavish-axi share`.

## AXI Architecture and Agent Ergonomics

lavish-axi is designed around agent ergonomics rather than human developer ergonomics. Key design choices include:

- **TOON output** (Token-Optimized Output Notation), long polling, and contextual disclosure to minimize token usage.
- **Skill-first discovery** — the recommended setup is a single `npx skills add` command that installs a skill file in the Agent Skills format; the CLI itself is fetched on demand via `npx -y lavish-axi`.
- **Session hooks** for Claude Code, Codex, OpenCode, and GitHub Copilot CLI that surface open sessions and visualization playbooks at the start of each agent session.
- **Playbook system** — built-in playbooks (`diagram`, `table`, `comparison`, `plan`, `code`, `input`, `slides`) teach agents good visualization patterns for common artifact types.

## Layout Safety and Feedback Controls

lavish-axi includes an open-time layout gate: the browser chrome masks each artifact until an in-iframe layout audit reports no error-severity findings. The audit checks for horizontal overflow, element overflow, clipped text, and overlapping text, and returns findings via `lavish-axi poll` as `layout_warnings` with selector, kind, overflow measurements, viewport width, and severity. This lets agents fix unreadable layouts before asking the human to review.

Feedback controls support native HTML inputs automatically. Custom clickable elements can be marked with `data-lavish-action`. The `window.lavish.queuePrompt()` API lets artifacts queue structured answers from interactive controls before a single submit.

## Export, Sharing, and Local-First State

- `lavish-axi export` writes a portable single-file HTML with local assets inlined and the annotation SDK stripped.
- `lavish-axi share` publishes the inlined artifact to ht-ml.app, public by default, with optional password protection; the response includes a one-time secret update key.
- All session state is stored under `~/.lavish-axi/` (or `LAVISH_AXI_STATE_DIR`) with no cloud dependency in the core loop.
- Per-asset and per-bundle inline caps default to 10 MB and 25 MB respectively, configurable via environment variables.

## Update: v0.1.32

The latest release is **lavish-axi v0.1.32**, published on June 27, 2026. The repository shows active development with CI and release-please automation, 91 forks, and 21 open issues as of early July 2026. The project is written primarily in JavaScript and distributed via npm.

## Features
- Local-first HTML artifact review with no cloud dependency in the core loop
- Element and text range annotation with precise DOM selectors
- Long-poll feedback delivery to agents via lavish-axi poll
- Open-time layout gate with in-iframe audit for overflow, clipped text, and overlapping text
- Layout warnings returned to agents with selector, kind, overflowPx, viewportWidth, and severity
- Built-in playbooks for diagrams, tables, comparisons, plans, code, inputs, and slides
- Skill-first setup via npx skills add in Agent Skills format
- SessionStart hooks for Claude Code, Codex, OpenCode, and GitHub Copilot CLI
- Live reload with iframe scroll position preservation
- Export to portable single-file HTML with local assets inlined
- Share to ht-ml.app with optional password protection
- Native HTML control interactivity without data-lavish-action markup
- window.lavish.queuePrompt() API for structured artifact feedback
- File-path keyed sessions with no opaque IDs
- TOON output and contextual disclosure for token efficiency
- Tailwind CSS v4 + DaisyUI v5 CDN fallback via lavish-axi design
- Mermaid diagram tooling for flows, architecture, state, and sequence diagrams
- Loopback-only server binding by default for local security
- Idle self-shutdown after configurable timeout
- AXI self-updater via lavish-axi update

## Integrations
Claude Code, Codex, OpenCode, GitHub Copilot CLI, Agent Skills (agentskills.io), Hermes Agent, ht-ml.app, Tailwind CSS v4, DaisyUI v5, Mermaid, npm, npx

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
0.1.32

## Links
- Website: https://github.com/kunchenguid/lavish-axi
- Documentation: https://github.com/kunchenguid/lavish-axi#readme
- Repository: https://github.com/kunchenguid/lavish-axi
- EveryDev.ai: https://www.everydev.ai/tools/lavish-axi