Hyperweave

FreeNot checked

HyperWeave gives agents a visual output surface: structured data in, branded SVG out. No JavaScript, no runtime. Works anywhere an image can be embedded. Badges

by InnerAura

GitHub Embed

About

HyperWeave gives agents a visual output surface: structured data in, branded SVG out. No JavaScript, no runtime. Works anywhere an image can be embedded. Badges, cards, charts, dashboards, diagrams, and more.

README

Portable visual output layer for agents.
One API call, one SVG. No JavaScript. Works everywhere.

The Problem

Agents need to show their work through plans, diagrams, dashboards, status cards, receipts, and reports. Markdown is portable but visually limited. HTML is expressive but not always durable across surfaces. Images are easy to share but lose their structure. Raw model output is flexible but inconsistent.

HyperWeave turns structured specs into deterministic visual artifacts. Each artifact is a self-contained SVG with layout, branding, data binding, and machine-readable metadata baked in. No JavaScript, no runtime, no dependencies. Readable by humans, recoverable by agents, and portable anywhere an <img> tag renders.

View as table

FORMAT	Renders identically across surfaces	Agent-Readable Metadata	Visual Fidelity	Token Efficiency	Zero Dependencies	SCORE
SVG	✓	✓	✓	~	✓	4.5
MARKDOWN	~	~	✗	✓	✓	3
HTML	✗	✓	✓	✗	~	2.5

Agentic Artifacts

HyperWeave receipts turn an AI coding session into a portable artifact that shows what it cost by model, tool usage, token spend, and context window history. Install the hook once and every session emits one:

pip install hyperweave
hyperweave install-hook

_{Claude Code · $116.66 · 151.1M tokens · 574 calls · opus-4.8}

_{Codex · $49.76 · 62.2M tokens · 718 calls · gpt-5.5}

_{The same Claude session if you fancy a proper receipt}

It reads your session's JSONL transcript from disk and detects the harness automatically (Claude Code or Codex). Theme it with any of the 8 primer variants, or the raw register tape:

hyperweave install-hook --genome cream   # any primer variant
hyperweave install-hook --genome raw     # the paper register tape

Want a different agent harness? Open an issue.

Diagrams

HyperWeave draws systems: pipelines, fan-outs, hubs, dependency graphs, swim lanes, state machines, sequences, rings, trees, and more, each rendered as a portable SVG. Nodes carry logos, labels, and small tags; edges carry labels and motion (a moving dash, a particle, or a pulse of light), and motion shows direction. Every diagram also embeds its full spec and a hash-verified digest (see Inside every artifact), so an agent reads the structure, not the pixels.

_{One artifact, every surface · the fan-out topology}

Compose this inline

hyperweave compose diagram --spec-file /dev/stdin -g primer --variant porcelain --surface inlay -o one-artifact.svg <<'JSON'
{
  "topology": "fanout",
  "title": "One Artifact, Every Surface",
  "subtitle": "One artifact, every surface · a self-contained SVG renders wherever markdown does",
  "notes": "every surface",
  "glyph_tint": "full",
  "nodes": [
    {
      "id": "artifact",
      "label": "HyperWeave SVG",
      "desc": "self-contained · portable",
      "role": "hero",
      "glyph": "hyperweave",
      "style": "card+glyph"
    },
    {
      "id": "github",
      "label": "GitHub",
      "desc": "README · Issues · PRs",
      "glyph": "github",
      "style": "card+glyph"
    },
    {
      "id": "obsidian",
      "label": "Obsidian",
      "desc": "vault · daily notes",
      "glyph": "obsidian",
      "style": "card+glyph"
    },
    {
      "id": "slack",
      "label": "Slack",
      "desc": "threads · unfurled",
      "glyph": "slack",
      "style": "card+glyph"
    },
    {
      "id": "email",
      "label": "Email",
      "desc": "inline · PDF export",
      "glyph": "gmail",
      "style": "card+glyph"
    },
    {
      "id": "agent",
      "label": "Agent Context",
      "desc": "hw:reasoning parsed",
      "glyph": "anthropic",
      "style": "card+glyph"
    }
  ]
}
JSON

_{Frontier serving · layered DAG with a telemetry skip edge}

Compose this inline

hyperweave compose diagram --spec-file frontier-serving -g primer --variant noir --surface inlay -o frontier-serving.svg

frontier-serving is a bundled preset; the URL API renders it by name at /v1/diagram/frontier-serving/primer.static.

_{MCP gateway · host → gateway → server, request and response as two lanes}

Compose this inline

hyperweave compose diagram --spec-file gateway -g primer --variant space --surface inlay -o mcp-gateway.svg

gateway is a bundled preset; the URL API renders it by name at /v1/diagram/gateway/primer.static.

_{Frontier handoff · beam relay across four labs}

Compose this inline

hyperweave compose diagram --spec-file frontier-handoff -g primer --variant noir --surface inlay -o frontier-handoff.svg

frontier-handoff is a bundled preset; the URL API renders it by name at /v1/diagram/frontier-handoff/primer.static.

Pick a layout


Flows	`pipeline` · `fanout` · `convergence`	stages in a line, one-to-many, many-to-one
Cycles	`ring` · `flywheel` · `state-machine`	a loop, a driven loop, legal state transitions
Structure	`dag` · `tree` · `stack` · `lanes`	dependencies, hierarchy, layers, ownership rows
Centered	`hub`	one thing at the middle of its world
Time	`sequence`	who calls whom, in order
Side by side	`comparison`	two options on one sheet

Thirteen layouts, forty bundled presets, one spec vocabulary. Render any preset by name: /v1/diagram/{preset}/primer.static.

Matrices - Generative Tables

HyperWeave matrices are structured tables rendered as portable SVGs. A single JSON description can produce comparison grids, registries, tiers, benchmark tables, numeric heatmaps, chips, glyphs, bars, and status maps, while carrying a machine-readable payload for agents.

_{One frame, every table · generated, not drawn}

View as table

READER		PIXELS	MOTION	READS VIA
GitHub README	github	✓	Yes	camo, css animation
VS Code preview	vscode	✓	Yes	markdown preview
Slack unfurl	slack	~	-	image proxy
Gmail body	gmail	~	-	img tag
Agent	mcp	✗	-	hw:payload, hwz/1, markdown twin

Compose this inline

hyperweave compose matrix --spec-file /dev/stdin -g primer --variant porcelain -o one-artifact.svg <<'JSON'
{
  "title": "One artifact. Many readers.",
  "subtitle": "how each consumer ingests the same SVG",
  "columns": [
    {
      "id": "reader",
      "label": "READER",
      "role": "label"
    },
    {
      "id": "mark",
      "label": "",
      "kind": "glyph",
      "glyph_tint": "full"
    },
    {
      "id": "pixels",
      "label": "PIXELS",
      "kind": "check"
    },
    {
      "id": "motion",
      "label": "MOTION",
      "kind": "pill"
    },
    {
      "id": "via",
      "label": "READS VIA",
      "kind": "chip"
    }
  ],
  "rows": [
    {
      "label": "GitHub README",
      "cells": [
        {
          "glyph": "github"
        },
        {
          "state": "full"
        },
        {
          "state": "on"
        },
        {
          "chips": [
            "camo",
            "css animation"
          ]
        }
      ]
    },
    {
      "label": "VS Code preview",
      "cells": [
        {
          "glyph": "vscode"
        },
        {
          "state": "full"
        },
        {
          "state": "on"
        },
        {
          "chips": [
            "markdown preview"
          ]
        }
      ]
    },
    {
      "label": "Slack unfurl",
      "cells": [
        {
          "glyph": "slack"
        },
        {
          "state": "partial"
        },
        {
          "state": "off"
        },
        {
          "chips": [
            "image proxy"
          ]
        }
      ]
    },
    {
      "label": "Gmail body",
      "cells": [
        {
          "glyph": "gmail"
        },
        {
          "state": "partial"
        },
        {
          "state": "off"
        },
        {
          "chips": [
            "img tag"
          ]
        }
      ]
    },
    {
      "label": "Agent",
      "cells": [
        {
          "glyph": "mcp"
        },
        {
          "state": "none"
        },
        {
          "state": "off"
        },
        {
          "chips": [
            "hw:payload",
            "hwz/1",
            "markdown twin"
          ]
        }
      ]
    }
  ],
  "notes": "pixels for humans · hw:payload for agents"
}
JSON

# Connectors preset
https://hyperweave.app/v1/matrix/connectors/primer.static?variant=porcelain

# Any table, one URL: base64url MatrixSpec JSON (8 KB cap)
https://hyperweave.app/v1/matrix/custom/primer.static?spec=<base64url>

# CLI, with the markdown twin alongside
hyperweave compose matrix --spec-file table.json -g primer --variant porcelain --markdown-out table.md

Another matrix configuration for visualizing benchmarks:

View as table

MODEL		SWE-bench Verified	INPUT (per Mtok)	OUTPUT (per Mtok)
FRONTIER · CLOSED WEIGHTS
Claude Fable 5	anthropic	95 %	$10	$50
Claude Opus 4.8	anthropic	88.6 %	$5	$25
GPT-5.5	openai	82.6 %	$5	$30
Gemini 3.1 Pro	gemini	80.6 %	$2	$12
OPEN WEIGHTS
DeepSeek V4-Pro	deepseek	80.6 %	$0.44	$0.87
Kimi K2.6	kimi	80.2 %	$0.95	$4
GLM-5	zai	77.8 %	$1	$3.2
Mistral Medium 3.5	mistral	77.6 %	$1.5	$7.5

SWE-bench Verified % · USD per Mtok · current flagships, jun 2026 · sources: vals.ai · artificialanalysis.ai · model cards

Compose this inline

hyperweave compose matrix --spec-file /dev/stdin -g primer --variant cream -o frontier-benchmarks.svg <<'JSON'
{
  "title": "Frontier vs Open",
  "subtitle": "coding & price · SWE-bench Verified against price per million tokens · current flagships, jun 2026",
  "columns": [
    {
      "id": "model",
      "label": "MODEL",
      "kind": "text",
      "align": "left",
      "role": "label"
    },
    {
      "id": "mark",
      "label": "",
      "kind": "glyph",
      "align": "center",
      "glyph_tint": "full"
    },
    {
      "id": "swe",
      "label": "SWE-bench Verified",
      "kind": "numeric",
      "align": "center",
      "polarity": "higher",
      "unit": "%"
    },
    {
      "id": "pin",
      "label": "INPUT",
      "sublabel": "per Mtok",
      "kind": "numeric",
      "align": "center",
      "polarity": "lower",
      "unit": "$"
    },
    {
      "id": "pout",
      "label": "OUTPUT",
      "sublabel": "per Mtok",
      "kind": "numeric",
      "align": "center",
      "polarity": "lower",
      "unit": "$"
    }
  ],
  "rows": [
    {
      "label": "Claude Fable 5",
      "cells": [
        {
          "glyph": "anthropic"
        },
        {
          "value": 95.0
        },
        {
          "value": 10
        },
        {
          "value": 50
        }
      ],
      "section": "FRONTIER · CLOSED WEIGHTS"
    },
    {
      "label": "Claude Opus 4.8",
      "cells": [
        {
          "glyph": "anthropic"
        },
        {
          "value": 88.6
        },
        {
          "value": 5
        },
        {
          "value": 25
        }
      ],
      "section": "FRONTIER · CLOSED WEIGHTS"
    },
    {
      "label": "GPT-5.5",
      "cells": [
        {
          "glyph": "openai"
        },
        {
          "value": 82.6
        },
        {
          "value": 5
        },
        {
          "value": 30
        }
      ],
      "section": "FRONTIER · CLOSED WEIGHTS"
    },
    {
      "label": "Gemini 3.1 Pro",
      "cells": [
        {
          "glyph": "gemini"
        },
        {
          "value": 80.6
        },
        {
          "value": 2
        },
        {
          "value": 12
        }
      ],
      "section": "FRONTIER · CLOSED WEIGHTS"
    },
    {
      "label": "DeepSeek V4-Pro",
      "cells": [
        {
          "glyph": "deepseek"
        },
        {
          "value": 80.6
        },
        {
          "value": 0.44
        },
        {
          "value": 0.87
        }
      ],
      "section": "OPEN WEIGHTS"
    },
    {
      "label": "Kimi K2.6",
      "cells": [
        {
          "glyph": "kimi"
        },
        {
          "value": 80.2
        },
        {
          "value": 0.95
        },
        {
          "value": 4.0
        }
      ],
      "section": "OPEN WEIGHTS"
    },
    {
      "label": "GLM-5",
      "cells": [
        {
          "glyph": "zai"
        },
        {
          "value": 77.8
        },
        {
          "value": 1.0
        },
        {
          "value": 3.2
        }
      ],
      "section": "OPEN WEIGHTS"
    },
    {
      "label": "Mistral Medium 3.5",
      "cells": [
        {
          "glyph": "mistral"
        },
        {
          "value": 77.6
        },
        {
          "value": 1.5
        },
        {
          "value": 7.5
        }
      ],
      "section": "OPEN WEIGHTS"
    }
  ],
  "sections": [
    "FRONTIER · CLOSED WEIGHTS",
    "OPEN WEIGHTS"
  ],
  "notes": "SWE-bench Verified % · USD per Mtok · current flagships, jun 2026 · sources: vals.ai · artificialanalysis.ai · model cards"
}
JSON

Inside the file: like every artifact, a matrix carries its full spec and a hash-verified digest, so an agent recovers the table rather than scraping pixels. Inside every artifact shows the mechanics.
Markdown twin: every matrix has a GFM projection of the same table. --markdown-out on the CLI, respond:"json" over HTTP, render_target="markdown" over MCP.

Inside every artifact

Every HyperWeave artifact is a re-ingestible object, not just an image. It carries its full spec (hw:payload) and a hash-verified digest (hwz/1 envelope), so an agent can work with it directly, never parsing pixels. Two tiers, two jobs. Here they are inside a diagram artifact:

recreate & modify: the complete spec

<hw:payload schema="diagram/1" media-type="application/json">
{
  "spec": {
    "title": "Service dependencies",
    "subtitle": "Service dependencies · a gateway fans to domain services, each grounding on its store",
    "topology": "dag",
    "zones": ["subsystems"],
    "nodes": [
      { "id": "web",     "label": "web",         "desc": "React SPA", "glyph": "react" },
      { "id": "gateway", "label": "API gateway", "role": "hero",      "kind": "router" },
      { "id": "auth",    "label": "Auth",        "desc": "tokens",    "kind": "shield" }
      <!-- … 5 more nodes · lossless -->
    ],
    "edges": [
      { "source": "web",     "target": "gateway",  "relation": "assert" },
      { "source": "gateway", "target": "auth",     "relation": "assert" },
      { "source": "auth",    "target": "postgres", "label": "reads", "label_style": "chip", "relation": "assert" }
      <!-- … 6 more edges · lossless -->
    ]
  }
}
</hw:payload>

the ≈200-token digest: know what an artifact is without opening it

<hw:envelope format="hwz/1" media-type="application/json">
{
  "v": "hwz/1",
  "id": "sha256:48b3de6494886c678f4c8efab4f0aa105922e315f8f62145548e17935175fb11",
  "k": "diagram",
  "title": "Service dependencies",
  "intent": "topology diagram: Service dependencies",
  "state": "active",
  "data": {
    "pattern": "dag",
    "n": 8,
    "hero": "API gateway",
    "nodes": { "web": "React SPA", "API gateway": "", "Auth": "tokens", "Orders": "Python svc", "Search": "query svc", "Postgres": "primary", "Kafka": "events", "Redis": "cache" },
    "edges": ["web → API gateway", "API gateway → Auth", "API gateway → Orders", "API gateway → Search", "Auth → Postgres (reads)", "Orders → Postgres", "Orders → Kafka (emits)", "Search → Redis (cache)", "API gateway → Postgres (direct read)"]
  },
  "frames": [{ "t": "diagram", "l": "Service dependencies" }],
  "prov": { "by": "hyperweave", "ver": "0.4.0a6", "genome": "primer.porcelain", "ts": "2026-07-15T02:01:15.613547+00:00" }
}
</hw:envelope>

The envelope is the lossy digest; only the payload round-trips.

The round-trip: extract hw:payload, edit the JSON, POST /v1/compose with it as diagram: byte-identical re-render. The envelope's id is the sha256 of the payload, so an agent verifies "this artifact really is this data" before trusting either.
The look is a pointer, not a copy: prov.genome: "primer.porcelain" names the aesthetics; payload plus that one string is the entire recreation recipe.

Read at a budget: the verb algebra

Pixels for humans, compact JSON for agents. The verb algebra is the read/write grammar over the two tiers: every verb picks how much of the artifact to load, from the ≈200-token envelope to the full payload, and no verb ever parses pixels.

The verbs, split two ways.

Write · mints a new artifact, returns a content-addressed link (/v1/a/{id}), never inline SVG:

Verb	What it does
`compose`	a spec → an artifact
`transform`	edit an artifact's spec → a new artifact (new id + lineage)

Read · never mutates the artifact:

Verb	What it does	Returns
`extract`	pull the payload, envelope, or markdown back out	the requested depth
`verify`	recompute the id, proving the artifact is its data	`{valid, id}`
`validate`	check a spec against the schema before composing	`{valid, type, genome}`
`diff`	compare two artifacts	the structural delta
`query`	ask a question of the envelope	the answer

Every verb runs the same over the CLI (hyperweave {verb}), HTTP (POST /v1/{verb}), and MCP (hw_{verb}):

# compose an artifact, then read its spec straight back, no rendering
hyperweave compose matrix --spec-file table.json -g primer -o table.svg
curl -X POST https://hyperweave.app/v1/extract \
  -H 'Content-Type: application/json' \
  -d '{"source": "<svg or /v1/a/{id} url>", "respond": "payload"}'

One transform, start to finish

Compose a bundled preset (or your own spec). This is the diagram whose payload and envelope appear above:

hyperweave compose diagram --spec-file service-dependencies -g primer --variant porcelain --surface inlay -o services.svg

Transform it through the artifact itself. transform verifies the hash, applies the patch to the embedded spec, re-validates, and mints a new artifact with a lineage entry recording exactly what changed:

hyperweave transform services.svg --patch-json '[
  {"op": "add", "path": "/nodes/-", "value": {"id": "billing", "label": "Billing", "desc": "invoices", "glyph": "stripe"}},
  {"op": "add", "path": "/edges/-", "value": {"source": "gateway", "target": "billing", "relation": "assert"}},
  {"op": "add", "path": "/edges/-", "value": {"source": "billing", "target": "postgres", "label": "writes", "label_style": "chip", "relation": "assert"}}
]'

The result is a new artifact: new id, one more service in the fan, and the response carries the new envelope, the lineage, and a /v1/a/{id} link to the new pixels:

And because the look is a pointer, the same spec re-renders under any variant: swap porcelain for noir in the URL and the whole diagram returns in the dark scheme, structure untouched.

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.

Four built-in genomes ship today. Custom genome generation via AI skill files coming soon.

brutalist · automata · chrome · primer

brutalist

_{22 variants · 8 dark: celadon · alloy · carbon · pigment · umber · ember · temper · onyx
14 light (6 shown): 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 _card	_{/v1/card/{username}/{genome}.static?variant={variant} (/v1/stats/… alias)} _{hyperweave.app/v1/card/eli64s/brutalist.static?variant=pulse}
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 · sigil}	_{/v1/divider/{seam\|sigil}/{genome}.static?variant={variant}} _{hyperweave.app/v1/divider/sigil/brutalist.static?variant=pulse}

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 _card	_{/v1/card/{username}/{genome}.static?variant={tone} (/v1/stats/… alias)} _{hyperweave.app/v1/card/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 _card	_{/v1/card/{username}/{genome}.static?variant={variant} (/v1/stats/… alias)} _{hyperweave.app/v1/card/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}

primer

_{8 variants · 4 light: porcelain · cream · dusk · petrol
4 dark: noir · carbon · space · anvil}

Signals _{animated state marks}	_{ping (passing) · spinner (building) · throb (warning) · shake (critical). One mark system, shared with the strip.} _{/v1/badge/{title}/{value}/primer.static?state={state}&variant={porcelain\|cream\|dusk\|petrol\|noir\|carbon\|space\|anvil}} _{hyperweave.app/v1/badge/BUILD/passing/primer.static?state=passing&variant=porcelain}
Dashboard _strip	_{/v1/strip/{title}/primer.static?data={tokens}&subtitle={text}&glyph={glyph}&variant={variant}} _{hyperweave.app/v1/strip/readme-ai/primer.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version&subtitle=eli64s/readme-ai&glyph=github&variant=porcelain}
Profile _card	_{/v1/card/{username}/primer.static?variant={variant} (/v1/stats/… alias)} _{hyperweave.app/v1/card/eli64s/primer.static?variant=porcelain}
Star Chart _{star history}	_{/v1/chart/stars/{owner}/{repo}/primer.static?variant={variant}} _{hyperweave.app/v1/chart/stars/eli64s/readme-ai/primer.static?variant=porcelain}
Marquee _{horizontal ticker}	_{/v1/marquee/{title}/primer.static?data={tokens}&variant={variant}} _{hyperweave.app/v1/marquee/readme-ai/primer.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,gh:eli64s/readme-ai.contributors,pypi:readmeai.downloads,gh:eli64s/readme-ai.last_push,pypi:readmeai.version,gh:eli64s/readme-ai.language&variant=porcelain}
Icons _{circle + square}	_{/v1/icon/{glyph}/primer.static?shape={circle\|square}&variant={variant}} _{hyperweave.app/v1/icon/github/primer.static?shape=circle&variant=noir}
Divider _aura	_{/v1/divider/aura/primer.static?variant={variant}} _{hyperweave.app/v1/divider/aura/primer.static?variant=porcelain}

	brutalist	automata	chrome	primer
Aesthetic	Raw material	Cellular	Metallic	Minimal
Variants	22 (8 dark, 14 light)	16 tones, any two pair	5 named	8 (4 dark, 4 light)
Motion	Animated border SMIL	Animated cell grid	Animated border SMIL	Animated state marks
Divider	`seam` · `sigil`	`dissolve`	`band`	`aura`

`/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}

Surface modes. A genome renders onto one of three surfaces: plate (opaque, its own background), inlay (bare, borrows the host page's light/dark), or twin (opaque and scheme-aware). Document and README embeds default to a scheme-adaptive surface so a single artifact reads correctly in both GitHub themes; standalone, slide, and raster destinations take plate. The CLI exposes --surface/--ground/--palette, and --faces writes the twin <picture> pair (<out>-light.svg / <out>-dark.svg).

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",
           data="text:NEW RELEASE,gh:anthropics/claude-code.stars,text:DOWNLOAD",
           genome="brutalist")

# Read or edit an existing artifact - the verb algebra
hw_extract(svg_or_url="<svg or /v1/a/{id} url>", respond="payload")
hw_transform(svg_or_id="<svg or /v1/a/{id} url>",
             mutations=[{"op": "replace", "path": "/title", "value": "SHIPPED"}])

# Return the SVG bytes inline instead of a hosted url (default respond="url")
hw_compose(type="badge", title="BUILD", value="passing", genome="brutalist", respond="svg")

hw_discover(what="all")   # the capability registry; full agent contract at /llms-full.txt

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 --data 'text:NEW RELEASE,gh:owner/repo.stars,text:DOWNLOAD' -g brutalist

# Session receipt from an agent transcript (Claude Code / Codex)
hyperweave compose receipt session.jsonl -o receipt.svg

# Validate a spec without rendering
hyperweave validate spec.json

# Profile card (live GitHub data, path-segment identity; 'stats' stays an alias)
hyperweave compose card eli64s -g chrome -o card.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

# The verbs: read or transform any artifact by handle, file, URL, or digest
hyperweave extract diagram.svg                      # the hw:payload seed as JSON
hyperweave diff v1.svg v2.svg --exit-code           # structural diff, git-style exit
hyperweave verify diagram.svg                       # payload ↔ envelope integrity
hyperweave query diagram.svg 'nodes[0].label'       # read one field
hyperweave transform diagram.svg --patch patch.json # mint a new artifact + lineage

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'

# Structured frames: /v1/{matrix|diagram}/{preset}/{genome}.{motion}
# (preset 'custom' takes a base64url ?spec=)
curl 'https://hyperweave.app/v1/matrix/connectors/primer.static?variant=porcelain'
curl 'https://hyperweave.app/v1/diagram/rag-pipeline/primer.static?variant=porcelain'

# 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"}'

# Verb algebra over an existing artifact: extract · verify · transform · diff · query
curl -X POST https://hyperweave.app/v1/extract \
  -H "Content-Type: application/json" \
  -d '{"source":"<svg or /v1/a/{id} url>","respond":"payload"}'

# Local server
hyperweave serve --port 8000

Output formats

Compose once, export to any of these (same artifact, same metadata):

`--format`	What you get
`svg`	the default: live, animated, adapts to the reader's light/dark theme
`svg-static`	the same picture with variables flattened and animation stripped, for renderers that don't run CSS
`png` · `webp`	rasterized bitmaps (needs `pip install 'hyperweave[raster]'`)
`ansi`	a terminal character-grid render

The HTTP API serves any of these by file suffix (GET /v1/a/{id}.png, width-bounded with ?w=), and a graphics-capable terminal (kitty, ghostty, wezterm) shows --format png inline.

Fonts embed in the SVG by default (--font-mode embed) so the file stands alone anywhere; cdn and system trade that portability for smaller bytes.

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:

Re-ingestible payload: the full spec (hw:payload) plus a hash-verified hwz/1 envelope, so an agent can recover, verify, and edit it - the basis of the verb algebra.
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 anywhere SVGs render: GitHub's Camo proxy, email clients, Notion embeds.
Accessibility: WCAG AA, prefers-reduced-motion, prefers-color-scheme, forced-colors, ARIA markup. Structural, not decorative.

Dimension	Count
Frame types	10 (badge, strip, icon, divider, marquee, card, chart, matrix, diagram, receipt)
Genomes	4 (automata, brutalist, chrome, primer)
Motion configs	6 (1 static + 5 border SMIL)
Glyphs	192 (183 brand marks + 9 geometric shapes)
Divider variants	10: 5 genome-themed (`band` chrome, `seam` + `sigil` brutalist, `dissolve` automata, `aura` primer) + 5 genome-agnostic (`block`, `current`, `takeoff`, `void`, `zeropoint`) at `/a/inneraura/dividers/`
Metadata tiers	5 (Tier 0 silent → Tier 4 reasoning)
Bundled fonts	5 (JetBrains Mono, Orbitron, Chakra Petch, Barlow Condensed, Inter), embedded per artifact, 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.

from github.com/InnerAura/hyperweave

Install Hyperweave in Claude Desktop, Claude Code & Cursor

Recommended · one command, every IDE

unyly install hyperweave

Installs into Claude Desktop, Claude Code, Cursor & VS Code — handles npx, uvx and build-from-source repos for you.

First time? Get the CLI: curl -fsSL https://unyly.org/install | sh

Or configure manually

Run in your terminal:

claude mcp add hyperweave -- uvx hyperweave

FAQ

Is Hyperweave MCP free?

Yes, Hyperweave MCP is free — one-click install via Unyly at no cost.

Does Hyperweave need an API key?

No, Hyperweave runs without API keys or environment variables.

Is Hyperweave hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Hyperweave in Claude Desktop, Claude Code or Cursor?

Open Hyperweave on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

Omni Video

An MCP server that transforms LLM-enabled IDEs into professional video editors by pre-processing footage into text proxies, generating motion graphics via HTML/

by buildwithtaza

ARA

Generate images, video and audio from any AI agent — one connector.

by ARA

YouTube

Transcripts, channel stats, search

by YouTube

EverArt

AI image generation using various models.

by modelcontextprotocol

Compare Hyperweave with

HyperweavevsOmni Video HyperweavevsARA HyperweavevsYouTube HyperweavevsEverArt

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All media MCPs

Command Palette

Hyperweave

About

README

The Problem

Agentic Artifacts

Diagrams

Pick a layout

Matrices - Generative Tables

Inside every artifact

Read at a budget: the verb algebra

One transform, start to finish

Genomes - Aesthetic DNA

brutalist

automata

chrome

primer

/a/inneraura/dividers/

Error fallback: SMPTE NO SIGNAL

Install

Entry Points

MCP

CLI

HTTP API

Output formats

How It Works

Data Connectors

Contributing

Install Hyperweave in Claude Desktop, Claude Code & Cursor

FAQ

Is Hyperweave MCP free?

Does Hyperweave need an API key?

Is Hyperweave hosted or self-hosted?

How do I install Hyperweave in Claude Desktop, Claude Code or Cursor?

Related MCPs

Omni Video

ARA

YouTube

EverArt

Compare Hyperweave with

`/a/inneraura/dividers/`