GitHub - InnerAura/hyperweave: Portable visual output layer for agents. One API call → self-contained SVG. Zero dependencies, works everywhere ⌬

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

The Problem

When an agent needs to produce something visual — a status card, a dashboard, a receipt of its work — it generates React, HTML, or pixels, locked in the environment that made it. Embed it in markdown, pass it to another agent — it breaks or loses context. There's no portable visual primitive for agents.

HyperWeave is that primitive. One API call returns a self-contained SVG with data binding, branding, and machine-readable metadata baked in. No JavaScript, no dependencies, no runtime. It renders in GitHub READMEs, Slack, Notion, docs, your site, email, VS Code, or terminal. Every surface that renders an <img> tag is a HyperWeave surface.

Agentic Artifacts

Every AI coding session produces a receipt — cost, tokens, tool distribution, session rhythm. One install, fully automatic.

hyperweave install-hook

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

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

_{Same data, different livery — claude-code}

_{Codex transcripts auto-detect from the JSONL shape}

The livery matches the agent that produced the session:

Agent	Livery
Claude Code	`claude-code`
Codex	`codex`
—	`voltage`
—	`cream`

Auto-detected from the session transcript. Pin a different default with hyperweave install-hook --genome voltage.

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.

brutalist · automata · chrome

brutalist

_{14 variants — 8 dark: celadon · alloy · carbon · pigment · umber · temper · ember · onyx
6 light: primer · depth · pulse · archive · signal · afterimage}

Signals _{state machine}	_{/v1/badge/{title}/{value}/{genome}.static?state={state}&variant={celadon\|carbon\|alloy\|temper\|pigment\|ember\|umber\|onyx\|archive\|signal\|pulse\|depth\|afterimage\|primer}} _{hyperweave.app/v1/badge/BUILD/passing/brutalist.static?state=passing&variant=celadon}
Dashboard _strip	_{/v1/strip/{title}/{genome}.static?data={tokens}&subtitle={text}&glyph={glyph}&variant={variant}} _{hyperweave.app/v1/strip/hyperweave/brutalist.static?data=gh:InnerAura/hyperweave.stars,pypi:hyperweave.version,gh:InnerAura/hyperweave.build&subtitle=InnerAura/hyperweave&glyph=github&variant=celadon}
Profile _{stats card}	_{/v1/stats/{username}/{genome}.static?variant={variant}} _{hyperweave.app/v1/stats/eli64s/brutalist.static?variant=celadon}
Star Chart _{star history}	_{/v1/chart/stars/{owner}/{repo}/{genome}.static?variant={variant}} _{hyperweave.app/v1/chart/stars/eli64s/readme-ai/brutalist.static?variant=celadon}
Marquee _{horizontal ticker}	_{/v1/marquee/{title}/{genome}.static?data={tokens}&variant={variant}} _{hyperweave.app/v1/marquee/readme-ai/brutalist.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,gh:eli64s/readme-ai.contributors,gh:eli64s/readme-ai.watchers,pypi:readmeai.downloads,gh:eli64s/readme-ai.last_push,gh:eli64s/readme-ai.pull_requests,gh:eli64s/readme-ai.issues,gh:eli64s/readme-ai.build,pypi:readmeai.version,gh:eli64s/readme-ai.language&variant=celadon}
Icons _{circle + square}	_{/v1/icon/{glyph}/{genome}.static?shape={circle\|square}&variant={variant}} _{hyperweave.app/v1/icon/github/brutalist.static?shape=circle&variant=celadon}
Divider _seam	_{/v1/divider/seam/{genome}.static?variant={variant}} _{hyperweave.app/v1/divider/seam/brutalist.static?variant=celadon}

automata

_{16 tones — crimson · copper · bone · solar · amber · sulfur · toxic · jade
abyssal · teal · steel · cobalt · indigo · violet · magenta · burgundy
pair any two via ?variant=primary&pair=secondary}

Signals _{state machine}	_{/v1/badge/{title}/{value}/{genome}.static?state={state}} _{hyperweave.app/v1/badge/BUILD/passing/automata.static?state=passing&variant=bone}
Dashboard _strip	_{/v1/strip/{title}/automata.static?data={tokens}&variant={tone}&pair={tone}&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=bone&pair=steel&glyph=github}
Profile _{stats card}	_{/v1/stats/{username}/{genome}.static?variant={tone}} _{hyperweave.app/v1/stats/eli64s/automata.static?variant=bone}
Star Chart _{star history}	_{/v1/chart/stars/{owner}/{repo}/{genome}.static?variant={tone}} _{hyperweave.app/v1/chart/stars/eli64s/readme-ai/automata.static?variant=bone}
Marquee _{horizontal ticker}	_{/v1/marquee/{title}/automata.static?data={tokens}&variant={tone}} _{hyperweave.app/v1/marquee/readme-ai/automata.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,gh:eli64s/readme-ai.contributors,gh:eli64s/readme-ai.watchers,pypi:readmeai.downloads,gh:eli64s/readme-ai.last_push,gh:eli64s/readme-ai.pull_requests,gh:eli64s/readme-ai.issues,gh:eli64s/readme-ai.build,pypi:readmeai.version,gh:eli64s/readme-ai.language&variant=bone}
Icons _square	_{/v1/icon/{glyph}/automata.static?shape=square&variant={tone}} _{hyperweave.app/v1/icon/docker/automata.static?shape=square&variant=cobalt}
Divider _dissolve	_{/v1/divider/dissolve/{genome}.static?variant={tone}&pair={tone}} _{hyperweave.app/v1/divider/dissolve/automata.static?variant=bone&pair=steel}

chrome

_{5 variants: horizon · lightning · abyssal · moth · graphite}

Signals _{state machine}	_{/v1/badge/{title}/{value}/{genome}.static?state={state}&variant={horizon\|lightning\|abyssal\|moth\|graphite}} _{hyperweave.app/v1/badge/BUILD/passing/chrome.static?state=passing&variant=horizon}
Dashboard _strip	_{/v1/strip/{title}/{genome}.static?data={tokens}&subtitle={text}&glyph={glyph}&variant={variant}} _{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&variant=horizon}
Profile _{stats card}	_{/v1/stats/{username}/{genome}.static?variant={variant}} _{hyperweave.app/v1/stats/eli64s/chrome.static?variant=horizon}
Star Chart _{star history}	_{/v1/chart/stars/{owner}/{repo}/{genome}.static?variant={variant}} _{hyperweave.app/v1/chart/stars/eli64s/readme-ai/chrome.static?variant=horizon}
Marquee _{horizontal ticker}	_{/v1/marquee/{title}/{genome}.static?data={tokens}&variant={variant}} _{hyperweave.app/v1/marquee/readme-ai/chrome.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,gh:eli64s/readme-ai.contributors,gh:eli64s/readme-ai.watchers,pypi:readmeai.downloads,gh:eli64s/readme-ai.last_push,gh:eli64s/readme-ai.pull_requests,gh:eli64s/readme-ai.issues,gh:eli64s/readme-ai.build,pypi:readmeai.version,gh:eli64s/readme-ai.language&variant=horizon}
Icons _{circle + square}	_{/v1/icon/{glyph}/{genome}.static?shape={circle\|square}&variant={variant}} _{hyperweave.app/v1/icon/youtube/chrome.static?shape=circle&variant=horizon}
Divider _band	_{/v1/divider/band/{genome}.static?variant={variant}} _{hyperweave.app/v1/divider/band/chrome.static?variant=horizon}

	brutalist	automata	chrome
Aesthetic	Raw material	Living cellular grid	Metallic precision
Variants	14 (8 dark, 6 light)	16 tones, any two pair	5 named
Motion	Animated border SMIL	Animated cell grid	Animated border SMIL
Divider	`seam`	`dissolve`	`band`

`/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            # CLI + SVG rendering (the base)
uv add 'hyperweave[serve]'   # + HTTP server  (hyperweave serve)
uv add 'hyperweave[mcp]'     # + MCP server   (hyperweave mcp)
uv add 'hyperweave[all]'     # + both servers
# or swap `uv add` for `pip install`

Requires Python 3.12+. The base install is CLI + rendering; the HTTP and MCP servers are optional extras so the core stays lean.

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 variants (automata: 16 solo tones, pair any two via &pair=...; chrome: horizon/abyssal/lightning/graphite/moth)
curl 'https://hyperweave.app/v1/badge/PYPI/automata.static?variant=teal&pair=violet&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	104 (98 brand marks + 6 geometric shapes)
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)
Bundled fonts	4 (JetBrains Mono, Orbitron, Chakra Petch, Barlow Condensed) — embedded in every SVG, no external font requests

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

Data Connectors

HyperWeave binds live data into any artifact through a unified token grammar (?data=...). Tokens are comma-separated; each token is either a literal (text:, kv:) or a live fetch (<provider>:<identifier>.<metric>).

Copy a token · view as table

Prefix	Source	Identifier shape	Metrics
`gh` / `github`	GitHub	`owner/repo`	`stars`, `forks`, `watchers`, `contributors`, `issues`, `pull_requests`, `last_push`, `build`, `license`, `language`
`pypi`	PyPI + pepy.tech	`package`	`version`, `license`, `python_requires`, `downloads`
`npm`	npm	`package`	`version`, `license`, `downloads`
`crates` / `cargo`	crates.io	`crate`	`version`, `downloads`, `recent_downloads`, `license`
`hf` / `huggingface`	Hugging Face	`org/model`	`downloads`, `likes`, `tags`, `pipeline_tag`, `library_name`, `license`, `gated`, `last_modified`
`docker`	Docker Hub	`namespace/repo`	`pull_count`, `star_count`, `last_updated`
`arxiv`	arXiv	`id` (e.g. `2310.06825`)	`title`, `authors`, `published`, `updated`, `categories`, `summary`, `journal_ref`, `doi`
`scorecard`	OpenSSF Scorecard	`owner/repo`	`score` (overall trust), plus per-check: `code_review`, `maintained`, `vulnerabilities`, `token_permissions`, ...
`dora`	GitHub Actions	`owner/repo`	`deploy_frequency`, `lead_time`, `change_failure_rate`, `mttr` (30-day window)
`text`	literal	—	renders the payload as displayed text
`kv`	literal	`KEY=VALUE`	static role-tagged value

Caching — live values for 5–10 min; a failed fetch caches 60s and shows — rather than a fabricated zero.
Isolation — each provider has its own circuit breaker, so one upstream outage can't trip the others.
Escaping — commas inside text: / kv: values escape as \,.

→ Open an issue to request a connector.

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.

Name		Name	Last commit message	Last commit date
Latest commit History 75 Commits
.github/workflows		.github/workflows
assets		assets
docs		docs
hooks		hooks
scripts		scripts
src/hyperweave		src/hyperweave
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
fly.toml		fly.toml
justfile		justfile
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

The Problem

Agentic Artifacts

Genomes — Aesthetic DNA

brutalist

automata

chrome

`/a/inneraura/dividers/`

Error fallback — SMPTE NO SIGNAL

Install

Entry Points

MCP

CLI

HTTP API

How It Works

Data Connectors

Contributing

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

The Problem

Agentic Artifacts

Genomes — Aesthetic DNA

brutalist

automata

chrome

/a/inneraura/dividers/

Error fallback — SMPTE NO SIGNAL

Install

Entry Points

MCP

CLI

HTTP API

How It Works

Data Connectors

Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`/a/inneraura/dividers/`

Packages