GitHub - Atipico1/hyperscribe
Key Points
- 1Hyperscribe is a system that enables Large Language Models to generate visual explanations by emitting semantic component JSON, significantly reducing token costs and improving output reliability compared to raw HTML generation.
- 2This approach slashes output token usage by 80-90%, provides schema-checked output for early error detection, and allows multi-agent reuse of its declarative JSON format.
- 3It renders self-contained HTML documents using a fixed catalog of 23 default components and bundled themes, handling all layout and styling decisions for consistent visual results.
Hyperscribe is a system designed to generate visual explanations and documentation by shifting the paradigm from large language models (LLMs) emitting raw HTML to emitting structured, semantic JSON data. This approach aims to produce more consistent, cheaper, and easier-to-revise visual outputs.
The core methodology revolves around a strict contract between the LLM and a dedicated, offline renderer. Instead of generating a complete HTML document, the LLM produces a JSON "envelope" adhering to the A2UI v0.9 specification. This envelope contains semantic component data, specifying components from a fixed catalog and their properties, without any styling or layout instructions. The renderer then interprets this JSON, handles layout, styling, validation, and packages the result into a self-contained HTML page or slide deck.
The JSON envelope structure includes fields such as a2ui_version, catalog, is_task_complete, and a parts array. Each item in the parts array defines a component (e.g., hyperscribe/Page, hyperscribe/Mermaid) and its props (semantic properties only, such as title or source, explicitly rejecting styling attributes like color or fontSize). Components can also contain children for hierarchical structures.
This architectural shift yields several practical consequences:
- Token Cost Efficiency: Output token costs are drastically reduced. A medium HTML page that might consume 5,000+ tokens can be represented by a Hyperscribe JSON envelope of typically 200-1,500 tokens, representing an 80-90% reduction.
- Schema-checked Output: The command-line interface (CLI) validates the generated JSON envelope against a predefined schema (
plugins/hyperscribe/spec/catalog.json) before rendering. This validation catches errors like missing required properties, unknown component names, or out-of-range enumerations, providing specific error messages (path: message) that the LLM can use for self-correction. - Multi-agent Reuse: Since the output format is declarative JSON, any system capable of emitting JSON, including other LLMs (Codex, Gemini CLI), RAG pipelines, or custom tooling, can drive the Hyperscribe renderer, promoting interoperability.
- Offline Capability: The renderer operates entirely offline with no runtime network dependencies, ensuring portability and privacy.
Hyperscribe provides a catalog of 23 default page-mode components (e.g., Image, Callout, CodeBlock, Mermaid, ArchitectureGrid, DataTable, StepList, FileTree) and 2 slide-mode-only components (SlideDeck, Slide). The design system is Notion-inspired, featuring pre-defined styles and layouts, with semantic data driving visual choices (e.g., instead of direct color codes). Four bundled themes (studio, midnight, void, gallery) offer light and dark modes, applied via CSS variable overrides.
The typical workflow involves a user initiating a command (e.g., /hyperscribe "draw a simple auth flow" in Claude Code). The system injects the SKILL.md prompt, providing the model with the component catalog and envelope format. The LLM then generates the semantic JSON envelope. A CLI tool (plugins/hyperscribe/scripts/render.mjs) validates this JSON against its schema; upon success, it builds a single, self-contained HTML document with inlined CSS and server-side rendering (SSR) per component. This HTML file is saved locally and automatically opened in the user's browser, allowing for offline access and sharing.