Agent-HTML: HTML Canvas for AI-Authored Artifacts

TL;DR

TL;DR: Agent-HTML is an Apache-2.0 workspace and runtime that turns agent-authored React and TypeScript artifacts into durable HTML surfaces with inspectable blocks, themed presentation, and a Vite-powered Canvas host that keeps rules, resources, examples, and revisions close to the artifact.

Source and Accuracy Notes

• Project page: agent-html.org
• Source repository: github.com/Sayhi-bzb/Agent-HTML
• License: Apache-2.0 (verified via GitHub API license.spdx_id)
• Source last checked: 2026-06-16

What Is Agent-HTML?

Agent-HTML is the position that agent output should not always be a chat bubble or a Markdown document. Dashboards, data views, comparisons, workflows, product mockups, themed reports, and review surfaces all need HTML as the expression layer. The project’s pitch is that markdown explains, but HTML makes the idea visible, spatial, styled, stateful, and interactive.

The system has three pieces. agent-html is the portable source workspace where agents write React and TypeScript artifacts. @agent-html/react provides the headless Artifact and Block protocol so rich HTML surfaces have stable, addressable regions. The Canvas host discovers artifacts, renders them through Vite, shows guard feedback, overlays block inspection controls, routes block prompts, and applies theme presets.

Repo-Specific Setup Workflow

Step 1: Install

npm install agent-html

Step 2: Create a local Canvas workspace

npx agent-html init

Step 3: Start the Canvas host

npx agent-html dev

The dev host runs the Canvas, which discovers artifacts in the agent-html/artifacts directory and renders them through Vite with the guard, block inspection, and theme preset overlays.

Step 4: Ask the agent to author an artifact

Build a dashboard artifact in agent-html/artifacts using Agent-HTML Canvas.
Read agent-html/README.md and agent-html/AGENTS.md first.

The agent reads the workspace README and the agent instructions, then writes a React artifact with the right Canvas conventions.

Deeper Analysis

The inspectable Block protocol

The most distinctive design choice is the Block protocol. Each visible region in an artifact carries Block metadata that gives the host a stable handle on the region. The host uses those handles to place prompt actions, pass compact context back to the agent workflow, and target follow-up revisions to a specific block. Artifact source does not see host privileges, so the protocol is a review surface, not an attack surface.

Themed presentation with semantic tokens

Themes, spacing, typography, and surface treatment are part of the artifact’s meaning. The host applies theme presets while the artifact source stays on semantic tokens and Canvas classes. That split is what makes a Kanban, a chart, an image and table layout, or a comparison view look the same across artifacts without each artifact redefining the same CSS.

Durable context, not chat state

The README is explicit that the context is durable. Rules, resources, examples, data, and artifacts live in the filesystem instead of disappearing into chat state. Canvas makes the nearest correct primitive, hook, helper, schema, fixture, or asset easier to find, so the agent is not rewriting the same UI from scratch on every session.

Guarded boundaries

The host internals, old runtime surfaces, generated bundles, and privileged APIs are separated from artifact source. The artifact sees only the Artifact and Block protocol, the Canvas classes, and the local resources. That separation is what lets a user trust an agent-authored surface enough to keep editing it after the chat moves on.

Revision routing

Canvas prompt routing uses artifact metadata, block ids, optional implementation files, and compact interaction state. The follow-up prompt can stay close to the part of the HTML surface that needs work, and the host scopes the prompt to that block. The result is a more focused revision loop than “rewrite the whole artifact” iteration.

Practical Evaluation Checklist

• [ ] Do your agent outputs need to be durable HTML rather than disposable chat text?
• [ ] Do you want inspectable blocks as the review surface rather than a single artifact handle?
• [ ] Are themed presets, semantic tokens, and Canvas classes a better fit than per-artifact CSS?
• [ ] Do you need revision routing that targets a specific block by id and metadata?
• [ ] Will you run the Canvas host through Vite with the same npm workflow as the rest of your stack?
• [ ] Is the “rules, resources, examples, data, and artifacts live in the filesystem” model a fit?
• [ ] Do you need separation between artifact source and host internals for trust reasons?

Security Notes

Agent-HTML’s security model is the guarded boundary between artifact source and host internals. The artifact cannot reach the host’s privileged APIs, old runtime surfaces, or generated bundles. The host is responsible for routing prompts, applying theme presets, and showing guard feedback, but the artifact source is constrained to the Artifact and Block protocol plus the Canvas classes and local resources.

In practice that means the trust boundary is the same as any other “user-supplied code runs in a sandbox” model. Treat the agent-html/artifacts directory as code that runs in a Vite dev server. Do not point it at untrusted user prompts without the guard and review loop, and review the artifact source before you publish it the way you would review any other commit. The npx agent-html init and npx agent-html dev commands are bootstrap commands, so review what they do in your environment before running them.

FAQ

Q: Is Agent-HTML a chat UI? A: No. The project’s tagline is “You don’t need a chat UI but a canvas with AI.” Agent-HTML is a workspace and runtime for durable HTML artifacts that an agent authors and a human can keep editing.

Q: How are blocks different from components? A: Components are the React building blocks. Blocks add Block metadata that gives the host a stable, addressable handle on a visible region. The host uses that handle to place prompt actions, pass context back to the agent, and scope follow-up revisions to a specific region.

Q: Does Agent-HTML replace a design system? A: No. The Canvas classes and theme presets are a starting point. Artifacts can bring their own design tokens and components, and the host applies the theme preset on top of whatever the artifact exposes.

Q: Can I use Agent-HTML without a specific agent? A: Yes. The agent-html npm package, the npx agent-html init workspace, and the npx agent-html dev Canvas host are all agent-agnostic. You can drive them with Codex, Claude Code, a custom agent, or a human author.

Q: Where does the project’s documentation live? A: The Canvas constitution, architecture, workspace, host, design-system, and reference docs are under apps/docs/content/docs/. The cold-start route for authoring artifacts is agent-html/README.md, and the repository operating rules are in AGENTS.md.

Conclusion

Agent-HTML is a focused bet on HTML as the right expression layer for agent output, with a workspace and a runtime that make the bet operational. The Block protocol, the theme presets, and the durable filesystem context are the three pieces that make it work. If your agent outputs need to be reviewed, edited, and presented, and you want a Canvas host that respects the trust boundary, Agent-HTML is worth a serious look. If your outputs are pure prose, markdown is still the right tool.

Related reading: GitHub Trending tools, Developer tools, tinykit, Runtime, wesight.