Hyperweave

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.

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

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.

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",
  "connector_palette": "colored",
  "nodes": [
    {
      "id": "artifact",
      "label": "HyperWeave SVG",
      "desc": "self-contained · portable",
      "role": "hero",
      "glyph": "hyperweave",
      "style": "card+glyph"
    },
    {
      "id": "github",
      "label": "GitHub",
      "desc": "README · PRs",
      "glyph": "github",
      "style": "card+glyph"
    },
    {
      "id": "obsidian",
      "label": "Obsidian",
      "desc": "vault · notes",
      "glyph": "obsidian",
      "style": "card+glyph"
    },
    {
      "id": "slack",
      "label": "Slack",
      "desc": "threads · unfurls",
      "glyph": "slack",
      "style": "card+glyph"
    },
    {
      "id": "email",
      "label": "Email",
      "desc": "inline · PDF",
      "glyph": "gmail",
      "style": "card+glyph"
    },
    {
      "id": "agent",
      "label": "Agent Context",
      "desc": "hw:reasoning",
      "glyph": "anthropic",
      "style": "card+glyph"
    }
  ]
}
JSON

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.

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.

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

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.

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:

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

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:

Read · never mutates the artifact:

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 -o services-billing.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", "exit": "bottom", "entry": "right"}}
]'

The result is a new artifact: new id, one more service in the fan, the envelope and lineage on stdout — and -o writes the new pixels to services-billing.svg:

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.