Visual Artifact Renderer

Turn an agent's work into something you can scan, understand, and share. Instead of another wall of Markdown, get a consistent visual page for a code review, architecture walkthrough, report, comparison, or dashboard.

Agents provide structured JSON; the CLI validates it, and the renderer turns it into a styled, interactive page.

Demo

Recorded with terminal-control

visual-artifact-demo.mp4

Try it with prompts

Ask your agent for a visual artifact when markdown would be hard to scan:

• Create a visual artifact explaining the authentication flow
• Compare these two solutions using a visual artifact
• Walk me through these code changes using a visual artifact

What it solves

LLM-generated HTML is brittle. It burns tokens, drifts in style, and is hard to validate.

Visual Artifact Renderer gives agents a smaller surface: pick known UI nodes, provide data, and let a trusted renderer handle the page. The model describes what to show; the renderer decides how it looks.

How it works

flowchart TB
  subgraph Agent["Agent"]
    A1["Inspect source code/data"]
    A2["Read node contract"]
    A3["Build VisualArtifactSpec JSON"]
  end

  subgraph CLI["visual-artifact CLI"]
    C1["Validate spec"]
    C2["Write artifact bundle"]
    C3["Start server if needed"]
  end

  subgraph Renderer["Next.js renderer"]
    R1["Fetch JSON"]
    R2["Render trusted adapters"]
  end

  subgraph Cloudflare["Optional Cloudflare publishing"]
    P1["Upload bundle to R2"]
    P2["Serve public URL via Worker"]
  end

  A1 --> A2 --> A3 --> C1 --> C2 --> C3 --> R1 --> R2
  C1 -.->|invalid spec| A3
  C2 -.->|--publish| P1 --> P2

Loading

The runtime path:

1. The agent runs visual-artifact contract and builds a VisualArtifactSpec.
2. The CLI validates the spec and writes an artifact bundle.
3. The renderer fetches artifact.json and renders trusted adapters.

The LLM never writes routes, imports, JSX, CSS, or full HTML for the renderer.

Features

• Constrained JSON contract for slug, title, optional artifactType/topics discovery metadata, optional data, and typed nodes.
• 30+ node types for prose, cards, tables, charts, timelines, Mermaid, SVG diagrams, tabs, accordions, logs, and diffs.
• Data-backed components that reference shared datasets by dataKey.
• Local-first storage under ~/.agents/skills/visual-artifact/artifacts unless overridden.
• Pi extension with the create_visual_artifact tool.
• Static renderer with live JSON, so new artifacts appear without rebuilding.
• Node-level annotations and in-memory AI Colab review mode.
• Optional Cloudflare publishing for durable public links.
• Safe rendering boundary: CLI validation before write, Zod parse before render, adapter-only UI.

Quick start

Most agents (default)

Install the CLI, renderer, and agent skill:

curl -fsSL https://github.com/iurysza/visual-artifact-renderer/releases/latest/download/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
npx skills add iurysza/visual-artifact-renderer --skill visual-artifact
visual-artifact doctor

Restart your agent if it was already running.

Pi

Install the CLI and renderer, then let Pi manage the skill and extension:

curl -fsSL https://github.com/iurysza/visual-artifact-renderer/releases/latest/download/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
pi install git:github.com/iurysza/visual-artifact-renderer
visual-artifact doctor

Run /reload in an existing Pi session or restart Pi.

That's it. Development setup, updates, pinned versions, and uninstall commands live in the CLI guide.

Create an artifact

From a file:

visual-artifact create my-spec.json

From stdin:

visual-artifact create - < my-spec.json

Minimal spec:

{
  "slug": "demo-report",
  "title": "Demo Report",
  "description": "A tiny Visual Artifact Renderer artifact.",
  "nodes": [
    {
      "type": "text",
      "props": {
        "text": "The agent supplied JSON. The renderer supplied the UI.",
        "size": "lg"
      }
    }
  ]
}

The CLI returns a local URL like:

http://127.0.0.1:9998/my-project/demo-report/

file-tree items may use src as create-time input. Relative paths must stay inside the canonical project root. Outside-project reads require a repeatable explicit --allow-read <dir> grant; the Pi tool never grants one. The CLI strips src after safely inlining content.

Annotations and AI Colab

Artifacts support node-level comment threads. Open an artifact and use Comments to select nodes, post replies, resolve threads, and copy a page link. Local writes require an existing artifact, are serialized per bundle, and use atomic mode-0600 replacement. Writable serving is loopback-only unless --allow-remote is explicit; browser writes must be JSON and satisfy same-origin checks.

Colab mode lets a formatter or agent attach suggested comments without persisting them. You can review, edit, delete, or export those comments as Markdown.

Details: ai-artifacts/docs/annotations.md.

Publishing

Use --publish to create a durable public URL through your own Cloudflare account:

visual-artifact create my-spec.json --publish

Published artifacts use R2 for artifact bundles and a Worker for the static renderer, JSON endpoints, and hosted annotation writes.

First-time deployment requires a cloned repo. Setup and deployment: ai-artifacts/docs/publishing.md.

CLI

Common commands:

visual-artifact contract
visual-artifact validate my-spec.json
visual-artifact create my-spec.json
visual-artifact serve --no-open
visual-artifact doctor

Full command reference: ai-artifacts/docs/cli.md.

Knowledge base

The docs are split like a small wiki. Start at the docs index, then follow the page that matches your task.

• Use CLI for install paths, command flags, server roles, and configuration.
• Use Annotations for comments, AI Colab, local writes, and hosted writes.
• Use Publishing for Cloudflare setup, deploys, --publish, and GitHub Actions.
• Use Architecture when changing boundaries, storage, routes, or data flow.
• Use Node reference when composing specs or adding node types.

Development

Run the complete pinned repository gate:

./scripts/verify.sh

For renderer development:

cd app
pnpm install --frozen-lockfile
pnpm dev              # http://localhost:9999/
pnpm test
pnpm lint
pnpm export:contract
pnpm verify:artifacts
pnpm build

For focused CLI development:

cd cli
bun install --frozen-lockfile
bun test
bun run typecheck
bun run build

Run pnpm visual:qa if you touch adapters or styling. Use Reliability for the full verification map and Release before publishing a new version.

Contract

The contract is compiled into the CLI from a shared source:

• shared/src/contract.ts
• cli/assets/contract.json (generated, tracked, and checked for drift)

Inspect it with:

visual-artifact contract

After contract changes:

cd app
pnpm export:contract
pnpm verify:artifacts

Repository layout

app/                   # Next.js renderer source + static export
cli/                   # Bun CLI source and compiled binary
shared/                # shared artifact contract + annotation schema
pi-extension/          # Pi tool wrapper for create_visual_artifact
skill/                 # agent-facing skill bundle
artifacts/             # local generated bundles, gitignored