hyperweave 0.2.21

Headless visual output layer for AI agents. One API call → self-contained SVG.

Headless visual output layer for AI agents.
One API call → self-contained SVG. No JavaScript. No dependencies. No runtime.
Works everywhere an <img> tag works.

---

The Problem

When an AI agent needs visual output, it generates React code or HTML that breaks across platforms, carries no brand identity, and is illegible to the next agent in the chain. There's no portable, reliable visual primitive for agents.

HyperWeave is that primitive. Semantic SVGs with embedded CSS state machines, accessibility markup, and machine-readable metadata. The artifact stays live, stays on-brand, and stays legible — whether it's rendered in a GitHub README, Slack, Notion, documentation site, email, VS Code, or terminal. Every surface that renders an <img> tag is a HyperWeave surface.

---

Agent Receipts

Every AI coding session produces a receipt — cost, tokens, tool distribution, session rhythm. One install, fully automatic. The artifact isn't a visualization of data. It is the record.

hyperweave install-hook

Every session drops a receipt SVG into .hyperweave/receipts/. No config, no server, no manual step. Skin auto-detects from the coding agent's runtime — Claude Code resolves to the warm-paper skin; everything else falls back to voltage. Pin a different default with hyperweave install-hook --genome cream.

_{262M tokens · 562 calls · 52 stages · $175 — voltage skin}

_{Same protocol, different genome — claude-code skin}

_{Rhythm strip — the same session data at 92px tall}

---

Genomes — Aesthetic DNA

A genome is a portable, machine-readable aesthetic specification. It encodes the complete visual identity — chromatic system, surface material, motion vocabulary, geometric form language — as a set of CSS custom properties that any agent can consume and apply consistently across every artifact type.

Three production genomes ship today. Custom genome generation via AI skill files coming soon.

chrome · brutalist · automata

chrome

_{chrome paradigm · metallic env-mapping · smooth corner radii}

Signals state machine	/v1/badge/{title}/{value}/{genome}.static?state={state} hyperweave.app/v1/badge/BUILD/passing/chrome.static?state=passing
Dashboard strip	/v1/strip/{title}/{genome}.static?data={tokens}&subtitle={text}&glyph={glyph} hyperweave.app/v1/strip/readme-ai/chrome.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version&subtitle=eli64s/readme-ai&glyph=github
Profile stats card	/v1/stats/{username}/{genome}.static hyperweave.app/v1/stats/eli64s/chrome.static
Star Chart star history	/v1/chart/stars/{owner}/{repo}/{genome}.static hyperweave.app/v1/chart/stars/eli64s/readme-ai/chrome.static
Marquee horizontal ticker	/v1/marquee/{title}/{genome}.static?data={tokens} hyperweave.app/v1/marquee/readme-ai/chrome.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version,pypi:readmeai.downloads,docker:zeroxeli/readme-ai.pull_count
Icons circle + square	/v1/icon/{glyph}/{genome}.static?shape={circle|square} hyperweave.app/v1/icon/youtube/chrome.static?shape=circle
Divider band	/v1/divider/band/{genome}.static hyperweave.app/v1/divider/band/chrome.static

brutalist

_{brutalist paradigm · sharp zero-radius · 5 border SMIL motions}

Signals state machine	/v1/badge/{title}/{value}/{genome}.static?state={state} hyperweave.app/v1/badge/BUILD/passing/brutalist.static?state=passing
Dashboard strip	/v1/strip/{title}/{genome}.static?data={tokens}&subtitle={text}&glyph={glyph} hyperweave.app/v1/strip/readme-ai/brutalist.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version&subtitle=eli64s/readme-ai&glyph=github
Profile stats card	/v1/stats/{username}/{genome}.static hyperweave.app/v1/stats/eli64s/brutalist.static
Star Chart star history	/v1/chart/stars/{owner}/{repo}/{genome}.static hyperweave.app/v1/chart/stars/eli64s/readme-ai/brutalist.static
Marquee horizontal ticker	/v1/marquee/{title}/{genome}.static?data={tokens} hyperweave.app/v1/marquee/readme-ai/brutalist.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version,pypi:readmeai.downloads,docker:zeroxeli/readme-ai.pull_count
Icons circle + square	/v1/icon/{glyph}/{genome}.static?shape={circle|square} hyperweave.app/v1/icon/discord/brutalist.static?shape=circle
Divider seam	/v1/divider/seam/{genome}.static hyperweave.app/v1/divider/seam/brutalist.static

automata

_{cellular paradigm · bifamily teal × amethyst · abyssal-cyber chromatics}

Signals chromatic variant	/v1/badge/{title}/automata.static?data={token}&variant={blue|purple|bifamily} hyperweave.app/v1/badge/DISCORD/JOIN/automata.static?glyph=discord&variant=purple
Dashboard strip · bifamily	/v1/strip/{title}/automata.static?data={tokens}&variant=bifamily&subtitle={text}&glyph={glyph} hyperweave.app/v1/strip/readme-ai/automata.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version&subtitle=eli64s/readme-ai&variant=bifamily&glyph=github
Profile stats card	/v1/stats/{username}/{genome}.static hyperweave.app/v1/stats/eli64s/automata.static
Star Chart star history	/v1/chart/stars/{owner}/{repo}/{genome}.static hyperweave.app/v1/chart/stars/eli64s/readme-ai/automata.static
Marquee horizontal ticker · bifamily	/v1/marquee/{title}/automata.static?data={tokens}&variant=bifamily hyperweave.app/v1/marquee/readme-ai/automata.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version,pypi:readmeai.downloads,docker:zeroxeli/readme-ai.pull_count&variant=bifamily
Icons circle + square	/v1/icon/{glyph}/automata.static?shape={circle|square}&variant={blue|purple} hyperweave.app/v1/icon/python/automata.static?shape=circle&variant=blue&v=20
Divider dissolve	/v1/divider/dissolve/{genome}.static hyperweave.app/v1/divider/dissolve/automata.static

	chrome	brutalist	automata
Surface	#000a14 deep void	#14532D dark field	#04060A void
Signal	#5ba3d4 metallic blue	#10B981 emerald	#1E849A teal · #6B3B8A amethyst
Profile	chrome (smooth, env-mapped)	brutalist (sharp, zero-radius)	brutalist (cellular paradigm)
Chromatic variant	—	—	blue / purple / bifamily
Motions	5 border SMIL	5 border SMIL	static, chromatic-pulse, rimrun, corner-trace
Divider	band (envelope drift)	seam (expansion joint)	dissolve (bifamily bridge)

_{The two automata signal badges share a URL and differ only in the chromatic variant: ?variant=blue renders the teal palette, ?variant=purple the amethyst, ?variant=bifamily both. Each genome declares its allowed variants in its JSON config; unknown values return 422.}

/a/inneraura/dividers/

block De Stijl composition	/a/inneraura/dividers/{slug} hyperweave.app/a/inneraura/dividers/block
current animated rainbow bezier	/a/inneraura/dividers/{slug} hyperweave.app/a/inneraura/dividers/current
takeoff rocket trajectory + thrust	/a/inneraura/dividers/{slug} hyperweave.app/a/inneraura/dividers/takeoff
void spectral bloom + hover state	/a/inneraura/dividers/{slug} hyperweave.app/a/inneraura/dividers/void
zeropoint aurora rule + nexus beacon	/a/inneraura/dividers/{slug} hyperweave.app/a/inneraura/dividers/zeropoint

Error fallback — SMPTE NO SIGNAL

Every broken <img> URL renders the SMPTE RP 219 test pattern with ERR_NNN matching the HTTP status, instead of a browser broken-image icon.

• _{/v1/badge/{title}/{value}/{unknown-genome}.static}
• _{hyperweave.app/v1/badge/TEST/value/unknown-genome.static}

---

Install

uv add hyperweave
# or
pip install hyperweave

Requires Python 3.12+.

---

Entry Points

Four interfaces, one pipeline. Every path produces the same artifact through the same compositor.

MCP

{
  "mcpServers": {
    "hyperweave": {
      "command": "hyperweave",
      "args": ["mcp"]
    }
  }
}

# Static badge
hw_compose(type="badge", title="BUILD", value="passing", genome="brutalist")

# Data-driven badge — unified token grammar (gh:owner/repo.metric, pypi:pkg.metric, ...)
hw_compose(type="badge", title="STARS", data="gh:anthropics/claude-code.stars", genome="brutalist")

# Strip with multiple live metrics
hw_compose(type="strip", title="readme-ai",
           data="gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version",
           genome="chrome")

# Marquee with mixed text + live tokens
hw_compose(type="marquee-horizontal",
           data="text:NEW RELEASE,gh:anthropics/claude-code.stars,text:DOWNLOAD",
           genome="brutalist")

# Discoverable shortcut for single-metric live badges
hw_live(provider="github", identifier="anthropics/claude-code", metric="stars")

hw_kit(type="readme", genome="brutalist", badges="build:passing")
hw_discover(what="all")

CLI

# Badge
hyperweave compose badge "build" "passing" --genome brutalist

# Strip with metrics
hyperweave compose strip "readme-ai" "STARS:2.9k,FORKS:278" -g brutalist

# Live data through the unified --data token grammar
hyperweave compose badge "STARS" --data 'gh:anthropics/claude-code.stars' -g brutalist

# Marquee with mixed text + live tokens
hyperweave compose marquee-horizontal --data 'text:NEW RELEASE,gh:owner/repo.stars,text:DOWNLOAD' -g brutalist

# Artifact kit
hyperweave kit readme -g brutalist --badges "build:passing,version:v0.2.0" --social "github,discord"

# Profile card (live GitHub data, path-segment identity)
hyperweave compose stats eli64s -g chrome -o stats.svg

# Star history chart
hyperweave compose chart stars eli64s/readme-ai -g brutalist -o chart.svg

# Custom genome from a local JSON file (validated against the profile contract)
hyperweave compose badge "DEPLOY" "live" --genome-file ./my-genome.json
hyperweave validate-genome ./my-genome.json

HTTP API

# URL grammar: /v1/{type}/{title}/{value}/{genome}.{motion}
curl 'https://hyperweave.app/v1/strip/readme-ai/brutalist.static?value=STARS:2.9k,FORKS:278'

# Live data via the unified ?data= grammar (works on badge / strip / marquee)
curl 'https://hyperweave.app/v1/badge/STARS/chrome.static?data=gh:anthropics/claude-code.stars'
curl 'https://hyperweave.app/v1/strip/readme-ai/brutalist.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks'
curl 'https://hyperweave.app/v1/marquee/SCROLL/brutalist.static?data=text:NEW%20RELEASE,gh:anthropics/claude-code.stars'

# Chromatic variant (automata's blue/purple/bifamily axis) and size (badge default/compact)
curl 'https://hyperweave.app/v1/badge/PYPI/automata.static?variant=purple&data=pypi:hyperweave.version'
curl 'https://hyperweave.app/v1/badge/build/passing/automata.static?size=compact'

# Genome-themed dividers
curl 'https://hyperweave.app/v1/divider/band/chrome.static'
curl 'https://hyperweave.app/v1/divider/seam/brutalist.static'
curl 'https://hyperweave.app/v1/divider/dissolve/automata.static'

# Genome-agnostic dividers
curl 'https://hyperweave.app/a/inneraura/dividers/zeropoint'

# POST compose
curl -X POST https://hyperweave.app/v1/compose \
  -H "Content-Type: application/json" \
  -d '{"type":"strip","title":"hyperweave","genome":"brutalist","value":"STARS:2.9k"}'

# Local server
hyperweave serve --port 8000

---

How It Works

Every artifact is the output of a single composition formula:

ARTIFACT = FRAME × PROFILE × GENOME × SLOTS × MOTION × ENVIRONMENT

Python builds context dicts. Jinja2 builds SVG. YAML defines config. Three layers, no mixing. Zero f-string SVG in Python.

ComposeSpec → engine.py → assembler.py (CSS) → lanes.py (validate) → templates.py (Jinja2) → SVG

Every artifact ships with:

• Semantic metadata — provenance, reasoning, spatial trace, aesthetic DNA. Machine-readable context so the next agent in the chain knows what it's looking at and why.
• CSS state machines — data-hw-status, data-hw-state, data-hw-regime drive visual transitions through the Custom Property Bridge. No JavaScript.
• Pure CSS/SMIL animation — all motion uses compositor-safe properties (transform, opacity, filter). No script tags. Works inside GitHub's Camo proxy, email clients, Notion embeds — anywhere SVGs render.
• Accessibility — WCAG AA, prefers-reduced-motion, prefers-color-scheme, forced-colors, ARIA markup. Structural, not decorative.

Dimension	Count
Frame types	9 (badge, strip, icon, divider, marquee-horizontal, stats, chart, receipt, rhythm-strip)
Genomes	3 (automata, brutalist, chrome)
Motion configs	6 (1 static + 5 border SMIL)
Glyphs	99 (93 Simple Icons + 6 geometric)
Divider variants	8 — 3 genome-themed (band chrome, seam brutalist, dissolve automata) + 5 genome-agnostic (block, current, takeoff, void, zeropoint) at /a/inneraura/dividers/
Metadata tiers	5 (Tier 0 silent → Tier 4 reasoning)
Paradigms	4 per frame (default, brutalist, chrome, cellular) — per-frame dispatch from genome
Bundled fonts	3 (JetBrains Mono, Orbitron, Chakra Petch — base64-embedded)

Stack: Pydantic, FastAPI, FastMCP v3, Jinja2, Typer.

---

Contributing

HyperWeave is early. If you're interested in building genomes, extending frame types, or just seeing what this looks like in your own README — join the Discord.

---