lavish-axi — AI가 만든 HTML을
"클릭해서 고치는" 에디터

에이전트는 멋진 HTML 산출물을 잘 만든다. 그런데 그걸 사람이 검토하고 고치는 과정은 여전히 "스크린샷 찍고 → 이거 저거 바꿔줘"라는 긴 글로 퇴화한다. lavish-axi는 그 망가진 루프를, 요소를 직접 클릭해 코멘트를 다는 로컬 에디터로 갈아끼운다. MCP가 아니라 "CLI"로 에이전트와 연결되는 새로운 패턴(AXI)의 교본이다.

1프로젝트 한 줄 요약

lavish-axi(Lavish Editor)는 AI 에이전트가 만들어 낸 HTML 파일을 로컬 브라우저로 열어, 사람이 화면 위 요소를 콕 집어 피드백을 보내면 그 피드백이 정확한 DOM 위치 정보와 함께 에이전트에게 되돌아가는 로컬 전용 리뷰 에디터입니다. 한 줄 슬로건은 "HTML is the new markdown." — 이제 에이전트의 결과물은 텍스트가 아니라 인터랙티브한 HTML 아티팩트이고, 그걸 다루는 전용 에디터가 필요하다는 주장입니다.

설치도, 서버도, 클라우드 계정도 필요 없습니다. npx lavish-axi plan.html 한 줄이면 로컬에 작은 HTTP 서버가 뜨고 브라우저가 열립니다. 개발자(또는 에이전트)는 lavish-axi poll plan.html로 사람의 코멘트를 기다리고, 사람은 화면에서 문단을 클릭하거나 텍스트를 드래그해 "여기 이렇게 바꿔줘"라고 답니다. npm 패키지명은 lavish-axi, 라이선스는 MIT, 만든 사람은 Kun Chen입니다.

2왜 주목받는가

2026년 들어 Claude Code·Codex·OpenCode 같은 코딩 에이전트가 일상화되면서, 에이전트가 내놓는 결과물이 "코드"를 넘어 "리치 HTML 산출물"(기획서·다이어그램·비교표·리포트)로 확장됐습니다. 그런데 이걸 검토하는 방법이 원시적이었습니다. lavish-axi는 바로 그 "검토 루프(review loop)"의 빈자리를 정확히 찔러서 트렌딩에 올랐습니다.

3기술 스택 전체 지도

lavish-axi는 화려한 프레임워크 더미가 아닙니다. 순수 JavaScript(ESM) + Express 서버 한 개로 된, 의외로 단출한 도구입니다. React도, 빌드된 프론트엔드 번들도 없습니다. 브라우저 UI("chrome"이라 부름)조차 서버가 렌더한 평범한 HTML + 바닐라 JS입니다. "작지만 단단하게" 만드는 법을 보여 주는 좋은 표본입니다.

언어 / 빌드

런타임 의존성 (단 6개)

4아키텍처 심화 분석

lavish-axi의 진짜 배울 점은 "에이전트 ↔ 사람 비동기 협업"을 단순한 부품으로 조립한 방식입니다. 핵심 흐름은 에이전트가 HTML을 쓴다 → CLI가 연다 → 사람이 코멘트를 단다 → CLI가 poll로 받아 고친다는 루프이고, 그 사이를 롱폴링 · SSE · postMessage · 파일감시라는 네 가지 검증된 웹 기술이 잇습니다.

전체 처리 흐름도

설계 패턴 ① — 파일 경로가 곧 신분증 (content-addressed)

session-store.js의 핵심 아이디어입니다. 세션 ID를 따로 발급하지 않고, 파일의 실제 경로(realpath)를 sha256 해시한 앞 16자를 세션 키로 씁니다. 그래서 같은 파일을 다시 열면 자동으로 같은 세션이 이어지고, 심볼릭 링크나 중복 경로도 하나로 합쳐집니다. "불투명한 ID"를 아예 없애는 깔끔한 설계입니다.

설계 패턴 ② — 샌드박스 iframe + postMessage 보안 경계

에이전트가 만든 HTML은 신뢰할 수 없는 코드일 수 있습니다. 그래서 아티팩트는 sandbox="allow-scripts ..." iframe 안에서 돌되 allow-same-origin은 일부러 뺍니다. 즉 아티팩트 안의 스크립트는 에디터(chrome)의 DOM을 절대 못 읽습니다. 둘 사이 통신은 전부 postMessage로만 오갑니다. 심지어 스크롤 위치조차 메시지로 주고받아야 할 만큼 철저히 격리돼 있습니다.

설계 패턴 ③ — 함수를 문자열로 직렬화해 브라우저로 배송

아티팩트에 주입되는 SDK(artifact-sdk.js)는 별도 번들 파일이 아닙니다. 서버가 createArtifactSdk.toString()으로 함수 자체를 문자열로 바꿔 (${...})() 형태로 응답에 실어 보냅니다. 서버에서 작성한 코드가 브라우저에서 실행되는데, 그 파일만큼은 빌드 단계가 필요 없습니다. 영리한(때론 논쟁적인) 코드 배송 기법입니다.

설계 패턴 ④ — 하트비트가 있는 롱폴링

에이전트의 poll은 사람이 코멘트를 달 때까지 무한정 기다려야 합니다. WebSocket을 쓰지 않고, 대신 HTTP 응답을 열어 둔 채 공백 바이트를 찔끔찔끔 흘려보내(heartbeat) 프록시·방화벽이 연결을 끊지 못하게 합니다. 사람이 코멘트를 보내는 순간 그 응답에 JSON을 담아 닫습니다. WebSocket 없이 "기다림"을 구현하는 실전 패턴입니다.

5디렉토리 구조 해부

모든 핵심 로직이 src/ 한 폴더에 모여 있습니다. 파일 하나가 책임 하나를 가지는, 읽기 쉬운 구조입니다.

src/ — 핵심 소스 (책임별 1파일)

그 외 주요 디렉토리

6학습 포인트 (기술별)

7시스템 요구사항

요구사항이 매우 가볍습니다. 무거운 GPU·DB·컨테이너가 전혀 없습니다.

8직접 해볼 실습 과제

🟢 입문 — 일단 써 본다

HTML 파일 하나를 만들고 npx lavish-axi index.html로 열어, 브라우저에서 문단을 클릭해 코멘트를 달아 보세요. 그 다음 다른 터미널에서 npx lavish-axi poll index.html을 실행해 방금 단 코멘트가 JSON으로 돌아오는지 확인합니다. lavish-axi playbook으로 내장 시각화 가이드도 출력해 보세요.

🟢 입문 — SDK 주입 관찰

브라우저 개발자도구로 페이지 소스를 보고, </body> 앞에 어떤 스크립트가 한 줄 끼워졌는지 찾으세요. 그게 html-transform.js가 한 일의 전부입니다. 원본 파일을 직접 열었을 때와 비교해 "휴대성"을 체감해 보세요.

🟡 중급 — 미니 lavish 클론

Express로 /poll(롱폴링)과 /comment(POST)만 가진 50줄짜리 서버를 만들어, 브라우저에서 보낸 텍스트가 대기 중인 poll 응답으로 흘러가게 하세요. lavish의 핵심 루프를 최소 재현하는 과제입니다.

🟡 중급 — postMessage 주석 엔진

sandbox iframe 안에서 클릭한 요소의 CSS 셀렉터를 계산해 부모 창으로 postMessage하는 스크립트를 작성하세요. artifact-sdk.js의 selector() 로직을 참고해 "고유 셀렉터"를 만드는 법을 익힙니다.

🔴 고급 — 나만의 AXI 만들기

axi-sdk-js 또는 직접 만든 래퍼로, 출력에 next_step 지시를 담는 CLI 도구를 설계하세요. 예: "스크린샷을 찍어 분석 → 다음 명령 안내". 에이전트가 설정 없이 그 CLI를 다단계로 따라오게 만드는 것이 목표입니다.

🔴 고급 — 자기종료 백그라운드 서버

detached 프로세스로 서버를 띄우고, /health 버전 핸드셰이크 + 유휴 타이머 기반 자동종료 + PID로 강제종료(fallback)를 구현하세요. cli.js의 ensureServer()가 좋은 참고 자료입니다.

9관련 기술 학습 로드맵

10핵심 키워드 사전

11참고 링크