Hyperscribe

I like visual explanations.

I do not like asking a model to dump raw HTML for them.

The result is usually ugly, expensive, and annoying to revise. You burn a pile of tokens on markup, tweak prompts to fix spacing, then re-generate the whole thing because one part looks off.

So I built the renderer myself.

Hyperscribe lets the model emit semantic component JSON instead of full HTML. The renderer handles layout, styling, validation, and offline packaging. You get a self-contained HTML page or slide deck that is cheaper to generate, easier to iterate on, and much more consistent.

Benchmark

Same source, same repo, same context.md, two spawned subagents.

Compared against nicobailon/visual-explainer.

Hyperscribe used 5,096 fewer output tokens in this run.

Benchmark artifacts live in benchmark/. Prompt-tuning notes from the diagram-first feedback loops live in benchmark/feedback-loops.md.

Components Gallery

Visual previews for 19 non-text page-mode components.

Why Hyperscribe

What I wanted was a better contract between the model and the renderer.

Instead of asking the LLM to emit a complete HTML document, Hyperscribe asks it to emit a JSON envelope against a fixed catalog of 23 default page components plus 2 slide-mode-only components, and ships the renderer itself.

That shift has three practical consequences:

• Token cost. A medium page of HTML runs 5,000+ output tokens. The equivalent Hyperscribe envelope is typically 200–1,500 tokens of JSON — an 80–90% reduction on the output side, which is the side that dominates latency and spend.
• Schema-checked output. The CLI validates the envelope before rendering. Missing required props, unknown component names, and out-of-range enums fail with a path: message error the model can read and retry against. HTML has no equivalent guardrail.
• Multi-agent reuse. The envelope format is declarative JSON — anything that can emit JSON can produce a Hyperscribe page. The Claude Code plugin is the first surface; Codex, custom agents, RAG pipelines, and hand-written tooling can target the same renderer without any LLM in the loop. The renderer is 100% offline and has no network dependencies at runtime.

That shift to a catalog-based JSON protocol is an intentional tradeoff — slightly less expressive (you can’t invent new layouts on the fly), significantly cheaper to run, and easier to validate and revise.

Install

Claude Code (recommended)

If you use Claude Code, start here.

If you want the /hyperscribe, /hyperscribe:slides, /hyperscribe:diff, and /hyperscribe:share slash commands, install via the plugin marketplace:

/plugin marketplace add Atipico1/hyperscribe
/plugin install hyperscribe@hyperscribe-marketplace

You can also install the skills with npx skills if you want the SKILL.md flow instead of slash commands, but the Claude Code plugin path is the recommended setup.

Any agent — Codex, Cursor, OpenCode, Gemini CLI, …

npx skills add Atipico1/hyperscribe

This installs four skills via the open agent skills CLI:

The CLI auto-detects which agents are present (Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Windsurf, Warp, and 40+ more) and writes each SKILL.md into that agent’s skill path. Pick a subset with --skill or target one agent with -a:

npx skills add Atipico1/hyperscribe --skill hyperscribe --skill hyperscribe-slides
npx skills add Atipico1/hyperscribe -a claude-code -a codex

The hyperscribe skill is the only one that carries the renderer; the other three depend on it being installed.

Manual use (any language / bespoke pipeline)

The renderer has zero runtime dependencies:

git clone https://github.com/Atipico1/hyperscribe.git
cd hyperscribe

# Pipe an A2UI envelope on stdin, write HTML to stdout or --out
echo '' | node plugins/hyperscribe/scripts/render.mjs --out page.html

Any agent or tool that can emit the JSON envelope described in plugins/hyperscribe/skills/hyperscribe/SKILL.md can drive this renderer.

Uninstall

# One-shot: removes all four skills from every agent (project + global scope)
curl -fsSL https://raw.githubusercontent.com/Atipico1/hyperscribe/main/uninstall.sh | bash

# Or use the skills CLI directly:
npx skills remove --agent '*' hyperscribe hyperscribe-slides hyperscribe-diff hyperscribe-share
npx skills remove --global --agent '*' hyperscribe hyperscribe-slides hyperscribe-diff hyperscribe-share

If you installed via Claude Code plugin marketplace, remove that separately:

/plugin uninstall hyperscribe@hyperscribe-marketplace

Rendered HTML output at ~/.hyperscribe/out/ is preserved. Delete manually with rm -rf ~/.hyperscribe if desired.

Quick start

Inside Claude Code, after installing the plugin:

> /hyperscribe "draw a simple auth flow: browser, app, identity provider, token exchange"

Claude picks the components (typically Page > Section > Mermaid + StepList), emits the JSON envelope, pipes it to scripts/render.mjs, and opens the resulting HTML file in your default browser. The output path is printed back so you can re-open or share it later.

A minimal envelope — the actual JSON Claude emits — looks like:

{
  "a2ui_version": "0.9",
  "catalog": "hyperscribe/v1",
  "is_task_complete": true,
  "parts": [
    {
      "component": "hyperscribe/Page",
      "props": { "title": "Auth flow" },
      "children": [
        {
          "component": "hyperscribe/Mermaid",
          "props": {
            "kind": "sequence",
            "source": "sequenceDiagram\n  Browser->>App: GET /login\n  App->>IdP: redirect\n  IdP-->>App: code\n  App->>IdP: exchange code\n  IdP-->>App: access_token"
          }
        }
      ]
    }
  ]
}

The renderer writes the HTML file to ~/.hyperscribe/out/ with a slugified filename and a timestamp, prints the absolute path, and exits. Re-opening the file later never re-queries the model — it is a plain HTML document on disk.

Commands

Component catalog 🎯

23 default components plus 2 slide-mode-only components. Full prop schemas, examples, and validation rules live in plugins/hyperscribe/references/catalog.md.

Slide mode only

These are intentionally separated from the default /hyperscribe page catalog.

The design system is Notion-inspired — warm neutrals, whisper borders, Inter font fallback chain — and every visual decision is owned by the renderer. Components carry semantic data only; styling props (color, backgroundColor, fontSize, className, etc.) are rejected by the schema. If a page wants a “red warning box” the envelope asks for Callout severity="warn", never a hex code.

Themes

Four bundled themes, each shipping both light and dark modes in a single CSS file. Pass --theme at render time to pick one; use --mode light|dark to force initial color mode (omit for prefers-color-scheme + localStorage).

Themes are pure CSS-variable overrides (plugins/hyperscribe/themes/*.css). Each defines tokens under [data-theme=""] (light) and [data-theme=""][data-mode="dark"] (dark). Semantic tones (--hs-tone-{info|warn|success|danger}-{bg|fg}) and surface palette (--hs-color-surface*) keep components legible across all four.

Breaking change in v0.4: notion is renamed to studio, linear is renamed to midnight. The old names no longer resolve — update any --theme notion / --theme linear calls to the new names. Running with the old names now throws Unknown theme "notion". Available: gallery, midnight, studio, void.

Your per-user theme + mode preference is stored at ~/.hyperscribe/preference.md after first run. A project-local ./.hyperscribe/preference.md overrides it. Delete either file to re-run first-run setup.

How it works

1. User runs a command. In Claude Code, the user types something like /hyperscribe "architecture for a rate limiter".
2. Skill prompt loads. The plugin injects SKILL.md and the command template, giving the model the catalog, envelope format, and the rule that props carry semantic data only.
3. Claude emits JSON. The model classifies the intent, picks components, and produces an A2UI envelope — no HTML, no CSS, no styling decisions. Unknown component names, missing required props, and out-of-range enums are caught in step 4, not left to a broken browser render.
4. CLI validates + renders. plugins/hyperscribe/scripts/render.mjs walks the envelope against the schema in plugins/hyperscribe/spec/catalog.json; on success it builds a single HTML document with inlined CSS and per-component SSR. Exit codes: 0 success, 1 JSON parse error, 2 schema validation failure, 3 IO error, 4 render runtime error.
5. Self-contained HTML lands on disk. Output is written to ~/.hyperscribe/out/-.html. No network, no external CSS, no build step — the file opens on a plane.
6. Open in browser. open on macOS, xdg-open on Linux — the agent prints the absolute path and a one-line summary so the user can re-open or share later.

Roadmap

• Rendering polish — better framing for complex diagrams, denser layouts where cards currently waste space, and more predictable output for long pages.
• Catalog growth — add a few more high-leverage components only where they reduce prompt complexity instead of expanding the surface area for its own sake.
• Installation polish — tighten setup across agents, improve diagnostics, and make it easier to verify that the right commands and skills were installed.

Contributing

PRs are welcome.

Before opening one:

• use Node 20+
• run npm test
• keep renderer and catalog changes in sync
• update docs when the component surface or install flow changes

If you are changing the envelope format or component schemas, start with plugins/hyperscribe/references/catalog.md and plugins/hyperscribe/spec/catalog.json.

Issues and discussion: github.com/Atipico1/hyperscribe/issues.

License

MIT — see LICENSE.

Copyright © 2026 Hyperscribe contributors.

Credits

• A2UI v0.9 (Google Developers Blog) — the envelope shape (a2ui_version, catalog, parts, is_task_complete) is borrowed so Hyperscribe documents can follow an existing structured UI contract.