hyperweave

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.

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.

	automata	chrome-horizon	brutalist-emerald
Signals	/v1/badge/PYPI/v0.2.11/automata.static?family={blue|purple}	/v1/badge/BUILD/{state}/chrome-horizon.static	/v1/badge/BUILD/{state}/brutalist-emerald.static
Dashboard	/v1/strip/readme-ai/automata.static?family=bifamily	/v1/strip/readme-ai/chrome-horizon.static	/v1/strip/readme-ai/brutalist-emerald.static
Profile cards	/v1/stats/eli64s/automata.static	/v1/stats/eli64s/chrome-horizon.static	/v1/stats/eli64s/brutalist-emerald.static
/v1/chart/stars/eli64s/readme-ai/automata.static	/v1/chart/stars/eli64s/readme-ai/chrome-horizon.static	/v1/chart/stars/eli64s/readme-ai/brutalist-emerald.static
Marquee	/v1/marquee/{title}/automata.static?rows=1&family=bifamily	/v1/marquee/{title}/chrome-horizon.static?rows=1	/v1/marquee/{title}/brutalist-emerald.static?rows=1
…/automata.static?rows=1&direction=up&family=bifamily	…/chrome-horizon.static?rows=1&direction=up	…/brutalist-emerald.static?rows=1&direction=up
Icons	/v1/icon/{glyph}/automata.static?shape={circle|square}&family={blue|purple}	/v1/icon/{glyph}/chrome-horizon.static?shape={circle|square}	/v1/icon/{glyph}/brutalist-emerald.static?shape={circle|square}
Banner	/v1/banner/HYPERWEAVE/automata.static?family=bifamily	/v1/banner/HYPERWEAVE/chrome-horizon.static	/v1/banner/HYPERWEAVE/brutalist-emerald.static

_{The two automata signal badges share a URL and differ only in the chromatic variant: ?family=blue renders the teal palette, ?family=purple the amethyst, ?family=bifamily both. The parameter name is provisional and likely to be renamed to ?variant= once brutalist skin variants land — treat the surface as unstable.}

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/TEST/value/nonexistent-genome.static — unknown genome → HTTP 404, value slab reads ERR_404.}

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"]
    }
  }
}

hw_compose(type="badge", title="build", value="passing", genome="brutalist-emerald")
hw_live(provider="github", identifier="anthropics/claude-code", metric="stars")
hw_kit(type="readme", genome="brutalist-emerald", badges="build:passing")
hw_discover(what="all")

CLI

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

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

# Banner with kinetic motion
hyperweave compose banner "HYPERWEAVE" -g brutalist-emerald -m cascade

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

# Profile card (live GitHub data)
hyperweave compose stats eli64s -g chrome-horizon -o stats.svg

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

# Timeline / roadmap from JSON items
hyperweave compose timeline --data roadmap.json -g chrome-horizon -o timeline.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-emerald.static?value=STARS:2.9k,FORKS:278

# Live data binding
curl https://hyperweave.app/v1/live/github/anthropics/claude-code/stars/chrome-horizon

# POST compose
curl -X POST https://hyperweave.app/v1/compose \
  -H "Content-Type: application/json" \
  -d '{"type":"banner","title":"HYPERWEAVE","genome":"brutalist-emerald","motion":"drop"}'

# Local server
hyperweave serve --port 8000

Session Telemetry

HyperWeave parses Claude Code transcripts into visual receipts — cost, tokens, tool distribution, cognitive phases. The artifact isn't a visualization of data. It is the record.

# Manual
hyperweave session receipt .claude/session.jsonl -o receipt.svg

# Autonomous — install once, every session gets a receipt
hyperweave install-hook

After install-hook, every Claude Code session automatically drops a receipt SVG into .hyperweave/receipts/. No config, no server, no manual step.

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.

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

Roadmap

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.