The solution
One source. Every protocol downstream.
AHTML compiles to every existing agent-web standard. You don't pick a side. You don't run a parallel server. You don't migrate.
One typed snapshot per page. Agents get MCP, OpenAPI, llms.txt, and safe priced actions. Browsers keep your HTML.
@ahtml 0.1 @url https://ahtml.dev/ @page_type home @ttl 300 @policy agents_welcome: yes license: MIT [document:why-ahtml] title: The HTML of the agent web summary: 5.6x fewer tokens, 91% to 100% accuracy (action) score_site category: read cost: free
Same page. Same content. One serialization for browsers, one for agents. Generated by the live toCompact() in @ahtmljs/schema.
@ahtml 0.1 @url https://github.com/DibbayajyotiRoy/AHTML @fetched 2026-07-12T07:18:52.798Z @ttl 600 @etag W/"15eeb6dc" @page_type home [document:ahtml-landing] title: AHTML — the HTML of the agent web author: Dibbayajyoti Roy published: 2026-05-12T00:00:00Z summary: Write your page once. AHTML emits MCP, OpenAPI, JSON-LD, llms.txt, and a typed semantic snapshot that uses 5-10× fewer tokens than HTML on lean pages, 50-100× on production-bloated pages. Drops into Next.js, Vite, SvelteKit. No migration. language: en tags: ahtml, agent-web, mcp, llms-txt, jsonld, openapi canonical_url: https://github.com/DibbayajyotiRoy/AHTML freshness: static (action) install label: Install via npm category: read method: GET execute: https://npmjs.com/package/@ahtmljs/next auth: none cost: free (action) join_waitlist label: Join waitlist category: send method: POST execute: /api/waitlist auth: none cost: free reversible: unsubscribe side_effects: create_subscription, send_email (action) run_benchmark label: Run the benchmark locally category: read method: GET execute: https://github.com/DibbayajyotiRoy/AHTML/tree/main/examples/benchmark cost: free (action) view_spec label: View v0.1 spec category: read method: GET execute: /spec cost: free @links canonical: https://github.com/DibbayajyotiRoy/AHTML related: product:mbp-14-m3, product:mbp-16-m3, product:aw-ultra-2, product:ipad-pro-m4 @meta generated_by: @ahtmljs/next 0.1.0
A typical product page ships 80 to 300 KB of nav, footer, tracking, and ad chrome. Less than 1% is the part an agent needs. Every token burned is paid for.
Schema.org describes what something is. It does not describe what you can do with it: cost, reversibility, side effects, auth, freshness. Agents guess.
A delete button and a $50,000 wire transfer look identical to a crawler. Without typed cost, reversibility, and confirmation, autonomous agents are one prompt injection from disaster.
AHTML compiles to every existing agent-web standard. You don't pick a side. You don't run a parallel server. You don't migrate.
Same content. Four serializations. Measured with the same tokenizers OpenAI and Anthropic use internally, gpt-tokenizer and @anthropic-ai/tokenizer. No text.length / 4 guesswork.
| Format | Bytes | Bytes (gzip) | Tokens o200k | Tokens Claude | × smaller (tokens, o200k) |
|---|---|---|---|---|---|
| HTML (server-rendered) | 28,400 | 6,240 | 6,810 | 6,412 | 1.0× |
| llms.txt | 459 | 337 | 139 | 151 | 49× |
| AHTML compact | 1,507 | 774 | 502 | 512 | 14× |
| AHTML JSON (pretty) | 1,728 | 834 | 508 | 542 | 13× |
Reproduce in 60 seconds: git clone github.com/DibbayajyotiRoy/AHTML && cd ahtml/examples/benchmark && npm install && npm run start. If gpt-tokenizer or @anthropic-ai/tokenizer is not installed, the corresponding column shows "·" rather than a fudged estimate.
The @ahtmljs/* scope splits cleanly: one schema everyone shares, five site adapters (plus the extractor plugin API behind them), agent-side clients in TypeScript and Python, and tooling that scores, certifies, indexes, and measures the result. The ahtml Python SDK on PyPI mirrors the TypeScript agent 1:1.
Full per-package endpoints, download counters, and STAR breakdowns in PACKAGES.md. Python SDK source in python/.
The canonical snapshot schema. Everything else depends on it.
For: Anyone authoring or validating AHTML without a framework adapter: server, client, or tooling.
$ npm install @ahtmljs/schema
import { snapshot, toCompact, lint } from '@ahtmljs/schema';Next.js plugin. One route, every well-known endpoint.
For: App Router sites on Next 14+/15 that want to be an MCP server.
$ npm install @ahtmljs/next
import { createAHTMLRoute } from '@ahtmljs/next/handler';Astro integration. All five endpoints, zero astro dependency.
For: Astro sites that want the same agent surface as the Next adapter.
$ npm install @ahtmljs/astro
import { ahtml } from '@ahtmljs/astro';SvelteKit adapter. One server hook or per-endpoint handlers.
For: SvelteKit apps that want the same five-endpoint agent surface.
$ npm install @ahtmljs/sveltekit
import { ahtmlHandle } from '@ahtmljs/sveltekit';Vite plugin. Same bytes as the Next adapter, every Vite framework.
For: SolidStart, vanilla Vite, or any Vite-based app without a dedicated adapter.
$ npm install @ahtmljs/vite
import { ahtml } from '@ahtmljs/vite';Hono adapter. The same emitter on every JavaScript runtime.
For: Hono apps on Node, Bun, Deno, Cloudflare Workers, or AWS Lambda.
$ npm install @ahtmljs/hono
import { ahtml } from '@ahtmljs/hono';The extractor pipeline behind every adapter, with a stable plugin API.
For: Custom domain extractors (recipes, job posts) or new framework adapters.
$ npm install @ahtmljs/extract
import { definePlugin } from '@ahtmljs/extract';Client SDK for AI agents that read the web. Works on any URL, adopter or not.
For: Anyone building an agent, scraper, or automation that reads other sites.
$ npm install @ahtmljs/agent
import { AHTMLClient } from '@ahtmljs/agent';The Python consumer SDK, 1:1 with the TypeScript agent.
For: Agent stacks in Python: LangChain, LlamaIndex, CrewAI, or raw SDKs.
$ pip install ahtml
from ahtml import AHTMLClientLangChain.js document loader. URL to embeddings in three lines.
For: RAG pipelines, vector stores, and retrieval chains on LangChain.js.
$ npm install @ahtmljs/langchain
import { AHTMLLoader } from '@ahtmljs/langchain';Scaffold, audit, score, certify, or proxy any site from your terminal.
For: Anyone adopting AHTML, or anyone who wants MCP tools from any URL today.
$ npm install -g @ahtmljs/cli
$ npx @ahtmljs/cli initPluggable KV and cache backends. Same caching from one server to an edge fleet.
For: Sites that cache snapshots or rate-limit agents across multiple instances.
$ npm install @ahtmljs/kv
import { UpstashKV } from '@ahtmljs/kv';WebMCP bridge. Expose page actions as native browser tools.
For: Sites that want in-page AI assistants to discover and run their typed actions.
$ npm install @ahtmljs/webmcp
import { registerWebMCP } from '@ahtmljs/webmcp';Agent-traffic analytics. See which agents actually read your site.
For: Publishers who ship AHTML and want to know who consumes it.
$ npm install @ahtmljs/insights
import { createInsights } from '@ahtmljs/insights';The language-agnostic conformance corpus and runner.
For: Anyone reimplementing AHTML in Go, Rust, PHP, or anything else.
$ npm install @ahtmljs/conformance
$ ahtml conformance manifest.jsonThe AHTML Index. A registry and crawler so agents can find adopters.
For: Anyone running or querying the registry of AHTML-enabled sites.
$ npm install @ahtmljs/index
$ ahtml submit https://example.comHosted score-badge service. Public, self-updating proof your site is agent-ready.
For: Publishers who want a README-embeddable score badge.
$ npm install @ahtmljs/badge
$ ahtml badge https://example.comThe dependency graph: schema ← extract ← next / astro / sveltekit / vite / hono (emit) · schema ← agent / langchain / ahtml-py (consume). One contract on both sides of the wire.
Each package is additive. Your existing pages keep rendering, your existing API keeps running; agents get an extra lane on the same origin.
Next.js sites: one route, every machine surface.
For: Next 14+ App Router or Pages Router projects.
npm install @ahtmljs/next @ahtmljs/schemaimport { withAHTML } from '@ahtmljs/next';
export default withAHTML({}, {
site: 'https://shop.com',
policy: { agents_welcome: true },
});import { createAHTMLRoute } from
'@ahtmljs/next/handler';
import { buildSnapshot } from
'@/lib/ahtml';
export const { GET, HEAD } =
createAHTMLRoute(buildSnapshot);Your snapshot now serves at:
/ahtml/*: typed snapshot per route (compact or JSON via Accept)/ahtml/mcp.json: auto-generated MCP tools manifest/ahtml/openapi.json: auto-generated OpenAPI 3.1 document/.well-known/ahtml.json: site-wide discovery manifest/llms.txt: compatibility shim for Cursor / Continue / ClineYour snapshot's actions become MCP tool definitions at /ahtml/mcp.json. No separate MCP server.
Actions with execute_url become full OpenAPI 3.1 operations. Codegen-ready.
Existing schema.org blocks become a Level-0 snapshot with zero developer work.
Auto-emit a clean llms.txt from registered routes. Free interop with Cursor / Continue / Cline.
Conditional GET via If-None-Match. ?since=<etag> returns just the change list.
Compact text for LLMs by default. Canonical JSON for signing and programmatic clients.
Every action carries auth, cost, reversibility, side effects, and confirmation level.
Token-bucket rate limit at the edge. Sites stay in control of what agents can do.
Detached JWS over canonical JSON, verified against a did:web identity. Agents detect tampering.
RFC 9421 signed requests. Sites know which agent is calling; imposters fail verification.
SPEC §4.7: agents rehearse an action before it mutates or charges. Simulated responses never touch real state.
Traffic analytics for publishers: which agents read you, in which format, with a tested zero-PII guarantee.
We're not a competitor to any of them. AHTML compiles to MCP, OpenAPI, JSON-LD, and llms.txt, and ingests from schema.org as a free Level-0 source.
| HTML | llms.txt | AHTML compact | AHTML JSON | |
|---|---|---|---|---|
| Token efficiency for agents | baseline | good | best | good |
| Typed entities | implicit | text only | ✓ | ✓ |
| Typed actions | implicit | text only | ✓ | ✓ |
| Cost / reversibility | ✕ | ✕ | ✓ | ✓ |
| Side-effect declarations | ✕ | ✕ | ✓ | ✓ |
| Site-wide policy | ✕ | partial | ✓ | ✓ |
| Freshness / TTL | ✕ | ✕ | ✓ | ✓ |
| Conditional fetch (ETag) | partial | ✕ | ✓ | ✓ |
| Pagination semantics | ✕ | ✕ | ✓ | ✓ |
| MCP-emittable | ✕ | ✕ | ✓ | ✓ |
| OpenAPI-emittable | ✕ | ✕ | ✓ | ✓ |
| Cryptographically signable | ✕ | ✕ | digest | ✓ |
= AHTML
Each card below is a real Next.js route on this site. Click it to see the regular HTML view. Then append /ahtml/ to the URL to see the same data as a typed snapshot. Or fetch it with Accept: application/ahtml+text.
AHTML is an open-source (MIT) snapshot format and toolkit that lets any website publish an agent-readable, token-efficient view of each page: typed entities plus typed actions with explicit cost, reversibility, auth, and side-effects. It auto-emits MCP, OpenAPI 3.1, JSON-LD, llms.txt, RSL, and Markdown from that single source, while browsers keep the same HTML.
No. AHTML emits MCP. MCP is the agent’s tool-calling protocol; AHTML is the per-page contract that auto-generates an MCP manifest at /ahtml/mcp.json from your existing site, so you don’t run a separate MCP server with parallel auth and deploys.
llms.txt is unstructured markdown: useful as a sitemap for IDE agents, but it can’t express typed entities or executable actions. AHTML auto-emits llms.txt as a compatibility shim and adds the typed contract; in the real-LLM benchmark llms.txt scored 89% on fact extraction vs 100% for AHTML JSON.
Measured with the real OpenAI and Anthropic tokenizers: 4.5× to 7.3× fewer tokens on the lean benchmark corpus (5.6× on the flagship page). On production-bloat pages of 200 to 500 KB the ratio scales toward 50× to 100×, because the snapshot stays near ~2 KB.
Yes. In a multi-model benchmark (146 runs, 20 fact-extraction tasks across gpt-4o-mini, claude-haiku-4.5, gemini-2.5-flash, and llama-3.3-70b), accuracy rose from 91% on raw HTML to 100% on AHTML JSON.
No. AHTML is additive: it adds endpoints (/ahtml/*, /.well-known/ahtml.json, /llms.txt) next to your existing routes, and the HTML you serve to browsers is unchanged.
Next.js 14+/15 App Router (@ahtmljs/next), Astro (@ahtmljs/astro), SvelteKit (@ahtmljs/sveltekit), Vite-based apps such as SolidStart (@ahtmljs/vite), and Hono on Node, Bun, Deno, Cloudflare Workers, and AWS Lambda (@ahtmljs/hono). You can also use @ahtmljs/schema directly with hand-rolled routes in any framework, and `npx @ahtmljs/cli init` detects and wires all five supported frameworks.
Yes. @ahtmljs/cli and @ahtmljs/agent extract typed snapshots from ordinary HTML (schema.org, OpenGraph, microdata, data-attributes), and `npx @ahtmljs/cli mcp <url>` turns any URL into MCP tools today.
Yes. `pip install ahtml` gives you the Python consumer SDK: a LangChain loader, an ETag/TTL-cached client, detached-JWS and did:web verification, and run_action with the same safety gate and dry-run sandbox as the TypeScript agent. Its canonical JSON output is byte-identical to the TypeScript reference.
Nothing. All sixteen @ahtmljs packages and the ahtml Python SDK are MIT-licensed open-source libraries that run inside your own app. There is no SaaS, no per-request pricing, and no lock-in.
Longer answers in the full FAQ and the 2026 comparison.
Python SDK on PyPI with byte-identical parsing, the extractor plugin API, and native Astro + SvelteKit adapters.
ahtml init scaffolds any supported framework; the score badge and agent-traffic insights reward publishing.
A language-agnostic conformance corpus with signed attestations, and the AHTML Index so agents can find adopters.
The dry-run sandbox: agents rehearse priced, irreversible actions and see signed predicted costs before money moves.
The full post-1.0 plan, with acceptance criteria mapped to CI tests, lives in ROADMAP.md.
One command. It detects Next, Astro, SvelteKit, Vite, or Hono and wires everything.