Hyperscribe는 LLM이 시각적 설명을 위한 HTML을 직접 생성하는 방식의 문제점(시각적 오류, 높은 토큰 비용, 수정의 어려움)을 해결하기 위해 개발된 렌더링 시스템입니다. LLM이 전체 HTML 문서 대신 "semantic component JSON" (A2UI envelope 형식)을 생성하도록 하여, 렌더러가 레이아웃, 스타일링, 유효성 검사 및 오프라인 패키징을 처리합니다. 이를 통해 더 저렴하고, 반복하기 쉬우며, 일관된 HTML 페이지 또는 슬라이드 데크를 생성할 수 있습니다.

핵심 방법론은 다음과 같습니다.

1. Semantic Component JSON Output: LLM은 고정된 컴포넌트 카탈로그(23개의 기본 페이지 컴포넌트와 2개의 슬라이드 모드 전용 컴포넌트)에 기반한 JSON envelope를 출력합니다. 이 envelope는 a2ui_version, catalog, is_task_complete, parts로 구성되며, 각 part는 컴포넌트 이름, 속성(props), 그리고 자식 컴포넌트(children)를 포함합니다. HTML 마크업이 아닌 의미론적 데이터를 전달합니다. 예를 들어, 경고 상자를 원하면 $Callout severity="warn"$을 요청하며, 색상(color), 배경색(backgroundColor), 폰트 크기(fontSize) 등 스타일링과 관련된 props는 스키마에 의해 거부됩니다.
2. 토큰 비용 절감: HTML 전체를 생성하는 대신, JSON envelope는 훨씬 적은 토큰을 사용합니다. 벤치마크에 따르면 raw HTML 대비 68% (5,096 토큰) 감소하여, 평균적으로 80-90%의 출력 토큰 절감 효과를 보입니다. 이는 LLM의 응답 지연 시간과 비용을 크게 줄여줍니다.
3. 스키마 기반 유효성 검사: CLI는 렌더링 전에 JSON envelope를 plugins/hyperscribe/spec/catalog.json의 스키마에 대해 검증합니다. 필요한 props의 누락, 알 수 없는 컴포넌트 이름, 범위를 벗어난 enum 값 등은 렌더링 이전에 오류로 감지되어 모델이 재시도할 수 있는 구체적인 path: message 오류를 제공합니다. HTML에는 이러한 가드레일이 없습니다.
4. 멀티 에이전트 재활용성: envelope 형식은 선언적 JSON이므로, JSON을 생성할 수 있는 모든 에이전트(Claude Code, Codex, Cursor, Gemini CLI 등)나 수동 도구가 동일한 렌더러를 활용할 수 있습니다.
5. 오프라인 렌더링: 렌더러는 100% 오프라인으로 작동하며 런타임에 네트워크 의존성이 없습니다. 생성된 HTML 파일은 자체 포함(self-contained)되어 언제든지 열 수 있습니다.

주요 특징 및 구성 요소는 다음과 같습니다.

• 컴포넌트 카탈로그: Page, Section, Image, Callout, CodeBlock, Mermaid, Sequence, ArchitectureGrid, FlowChart, DataTable, Chart, StepList 등 다양한 시각화 및 구조화 컴포넌트들을 제공합니다. SlideDeck, Slide는 슬라이드 모드 전용 컴포넌트입니다.
• 테마 시스템: studio, midnight, void, gallery의 네 가지 내장 테마를 제공하며, 각 테마는 라이트 및 다크 모드를 지원합니다. 테마는 CSS variable 오버라이드를 통해 구현되며, 모든 시각적 결정은 렌더러가 담당합니다.
• 통합 및 사용: Claude Code 플러그인(hyperscribe, hyperscribe:slides, hyperscribe:diff, hyperscribe:share 슬래시 커맨드)을 통해 쉽게 설치 및 사용할 수 있습니다. npx skills add Atipico1/hyperscribe 명령어로 다른 오픈 에이전트(Codex, Cursor 등)에도 설치 가능하며, node plugins/hyperscribe/scripts/render.mjs 스크립트를 통해 수동으로 JSON envelope를 stdin으로 받아 HTML을 출력할 수도 있습니다.
• 렌더링 프로세스: 사용자가 명령을 실행하면, SKILL.md와 명령 템플릿이 모델에 주입되어 JSON envelope를 생성하게 합니다. 이 envelope는 plugins/hyperscribe/scripts/render.mjs에 의해 스키마 검증 후 단일 HTML 문서로 변환됩니다. 결과 파일은 ~/.hyperscribe/out/에 저장되며, 브라우저에서 자동 열람됩니다.
• 라이선스: MIT 라이선스를 따릅니다.

Hyperscribe는 LLM이 시각적 결과물을 생성하는 방식의 패러다임을 전환하여, 효율성, 유효성, 재활용성을 극대화하는 것을 목표로 합니다.