Agent-HTML: React Artifacts as the Output Surface for Coding Agents
You don't need a chat ui but a canvas with ai.
At a glance
- What is it?
- Agent-HTML replaces the chat transcript with a filesystem-backed React canvas, where agents write TypeScript artifacts and humans review addressable Block regions. It is an alpha-stage tool for teams whose agent output needs layout, state and interaction rather than prose.
- Who is it for?
- Adopt Agent-HTML if your agent already produces dashboards, comparison tables or internal tools that get flattened by Markdown, and you are willing to accept an alpha release cadence: both published versions are v0.1.0-alpha, so pin the version and read the package-level license files before shipping anything. Skip it if you need a hosted chat interface, a stable API surface, or a runtime that works without a local Vite dev server.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 56 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap Agent-HTML is aimed at: agent output that outgrows Markdown
The README draws the line itself: Markdown is good for prose, lists and code, but a roadmap needs lanes, a dataset needs tables and charts, and a product concept needs layout. Agent-HTML exists for the moment when an agent's answer should become a surface rather than a document. That framing tells you the intended user. This is not for someone who wants a nicer chat window. It is for someone who has watched an agent produce a Kanban board or a chart specification inside a chat bubble and then had to copy it somewhere else to actually use it. The project's own examples are operational dashboards, Kanban boards, data reports, briefs, charts, tables, comparison views and focused internal tools. The common thread is that a human needs to scan, compare, filter or revise the result, not just read it once. The pitch is that the artifact should live in the filesystem as a React and TypeScript file, so it survives after the conversation that produced it has scrolled away.
How Canvas splits the source workspace from the host
The architecture has three named pieces. The first is `agent-html`, described as the portable source workspace where agents write React and TypeScript artifacts. The second is `@agent-html/react`, a headless package that provides the `Artifact` and `Block` protocol, giving rich HTML surfaces stable, addressable regions. The third is the Canvas host, which discovers artifacts, renders them through Vite, shows validation diagnostics, overlays block inspection controls, routes block prompts, and applies theme presets. That division is the whole design. Artifact source stays on one side, and host privileges, generated bundles and application internals stay on the other. The README calls this a validated boundary and lists it under what it means to build for agent workflows. The practical consequence is that an agent writing an artifact does not get access to whatever the host process can reach. For a tool whose entire input is model-generated code, that is the right default, and it is the kind of constraint that is easy to skip when the goal is a fast demo.
Block metadata is the mechanism that makes revision targeted
The most concrete design decision in the README is that `Block` metadata lets the host target one visible region, place prompt actions on it, and pass compact context back into the agent workflow. Canvas prompt routing then uses artifact metadata, block ids, optional implementation files and compact interaction state. Read that sequence carefully, because it is not the same as sending the whole file back to the model. A follow-up prompt is scoped to a block id plus whatever interaction state was captured, which means the agent is told which region needs work rather than being asked to re-derive the entire artifact from scratch. The README describes the goal as keeping follow-up prompts close to the part of the HTML surface that actually needs work. Whether that holds up in practice depends on how well block boundaries are drawn in a given artifact, and the README does not say what happens when a requested change crosses two blocks. That is a gap worth noting, not a flaw that can be confirmed from the material.
Getting a canvas running: three commands and a prompt
The Quick Start is short. Install the npm package with `npm install agent-html`. Create a local Canvas workspace with `npx agent-html init`. Start the Canvas host with `npx agent-html dev`. After that, the README suggests asking your agent to build or revise a React artifact in `agent-html/artifacts`, with a sample prompt that tells the agent to read `agent-html/README.md` and `agent-html/AGENTS.md` first. Those two files are the cold-start route for authoring, and the README points to `agent-html/README.md` as the place where the local Canvas resources are documented: UI primitives, hooks, helpers, schemas, fixtures, assets, semantic CSS classes, examples and source rules. If you are working inside the repository rather than consuming the package, the development path is `npm run dev`, with `npm run test`, `npm run typecheck` and `npm run lint` as the listed checks. Note that the npm package and the repository checkout are two different entry points, and the README does not spell out how their workspaces relate.
Theming sits on the host side, which keeps artifact source portable
Themes, spacing, typography and surface treatment are applied by the host, while artifact source is expected to stay on semantic tokens and Canvas classes. This is a reasonable split: an artifact written once can be re-rendered under a different theme preset without editing the artifact. It also means the visual result of an artifact is not fully determined by its own source, which is a trade-off. If you hand someone a single artifact file, you are not handing them its appearance. The README frames presentation as part of the artifact, but the mechanism that makes presentation swappable is the same mechanism that makes it non-portable on its own. The project ships theme presets as a host feature, shown in `public/theme.gif`, and the README does not enumerate what presets exist or whether custom presets are supported. Anyone whose workflow depends on a specific visual identity should confirm that before committing.
Where Agent-HTML is the wrong tool
Two limitations follow directly from the described design. First, this is a local dev-server workflow. The host renders artifacts through Vite, and the documented commands are `npx agent-html dev` and `npm run dev`. Nothing in the README describes a deployment story, a static export, or a hosted mode, so if your requirement is to send a stakeholder a link, this is not that. Second, both published releases are alpha: v0.1.0-alpha.1 and v0.1.0-alpha.2, dated within two days of each other in late May 2026. An alpha version number is not a judgement about code quality, but it does tell you the package interface is still moving. The README also states that license terms vary by package and that historical App and Runtime material lives under `_archive` for reference only, which suggests the project has already reorganized itself at least once. If your team needs a frozen API or a support commitment, this is the wrong moment. A plain Markdown answer plus a screenshot remains a better fit for one-off explanations.
How this differs from a chat UI or a notebook
The repository description is blunt: you do not need a chat UI but a canvas with AI. Compare that to the two obvious alternatives. A chat interface keeps the artifact inside a transcript, where it is rendered by the host's message renderer and is not a file you can open, diff or commit. Agent-HTML inverts that: the artifact is a React and TypeScript file in `agent-html/artifacts`, and the chat is only the input method. A notebook takes the opposite approach to state. It keeps code and output in one linear document, which is good for a sequence of steps and awkward for an interface with controls, filters and lanes. Agent-HTML's unit is a component with addressable blocks, not a cell. The cost of that choice is that you need a React toolchain and a Vite host running, which a notebook or a chat window does not ask of you. The benefit is that the output is a real front-end file you can keep.
Maintenance cost and the license question
The README's license section is deliberately unhelpful in the way that matters: terms vary by package, and the instruction is to check the folder you use. The repository is listed as Apache-2.0, and the root `LICENSE` is the reference point, but the README explicitly says package-level license files may differ. For a project that ships a CLI (`agent-html`), a headless protocol package (`@agent-html/react`) and a host, that means three things to check rather than one. I am not giving legal advice here; the point is that you cannot assume the root license covers everything you install. On maintenance, the signals available are the release dates and the last push timestamp of 2026-07-22. The release history is thin, and the README points readers to `taste/README.md` and `taste/agent-ergonomics/README.md` for repo-level judgment systems and agent-facing workspace ergonomics, which reads like internal process documentation that has been published rather than a stable external contract. Budget for reading those files before you ask an agent to author anything nontrivial.
Editorial conclusion
Adopt Agent-HTML if your agent already produces dashboards, comparison tables or internal tools that get flattened by Markdown, and you are willing to accept an alpha release cadence: both published versions are v0.1.0-alpha, so pin the version and read the package-level license files before shipping anything. Skip it if you need a hosted chat interface, a stable API surface, or a runtime that works without a local Vite dev server. Verify three things first: that the package you install carries the same license terms as the root LICENSE, that npx agent-html init writes a workspace layout you are happy to commit, and that your agent can actually follow the agent-html/README.md and AGENTS.md cold-start instructions without extra hand-holding.
Community notes