Getting Started with agent-html

agent-html is a local CLI engine for agents that need to produce safe, inspectable static artifacts.

The ahtml package owns config, engine, and CLI. Vite, React, Tailwind, shadcn/ui, theme files, and UI components live in your local project. Agents do not write arbitrary HTML, CSS, Tailwind classes, scripts, event handlers, React props, Radix props, or shadcn props.

Primary rule

Run ahtml init first. Then treat the schema as the source of truth for component names, props, children, and render config values.

1. Initialize the local integration

ahtml init
ahtml status
ahtml doctor

ahtml init delegates Vite + shadcn setup to your local project, then writes the ahtml integration config and renderer adapter files.

2. Read the schema

ahtml schema --format prompt

Use the schema output to learn the registered components, allowed props, allowed children, and finite render config values.

3. Write a document

A valid document needs a <page> root.

artifact.agent.html

<meta-agent
  theme="neutral"
  density="comfortable"
  tone="report"
  width="article"
/>

<page title="Review">
  <card title="Summary">
    This artifact was written with standard agent-html components.
  </card>
</page>

4. Validate before building

ahtml validate --input artifact.agent.html

Validation catches unknown components, unknown props, blocked implementation details, invalid children, and invalid render config values before artifact generation.

5. Build the artifact

ahtml build --input artifact.agent.html --out dist/html

The output is a static artifact directory that can be opened, shared, deployed, or archived.

6. Preview locally

ahtml preview --input artifact.agent.html --out dist/html --port 4173

Preview serves the same static output produced by build. It does not use a separate renderer.

Inspect the result

ahtml inspect --input artifact.agent.html
ahtml inspect --dir dist/html

Use inspect to review effective config and component usage without reading project source.

Quick Start