Aihu — agentic discovery and interaction, for human purpose.

Say EYE-hoo · 爱护 (àihù) · "to cherish and protect."

Aihu builds durable Web Components your AI agent can read and drive — not disposable UI it has to generate. An agent inspects a real component through its llms.txt + MCP manifest and calls its actions on the live, on-screen instance. The thing the user sees is the thing the agent drives, not a throwaway interface regenerated every turn.

npx create-aihu my-app --template agent   # a durable component an AI can drive — running in one command

You author .aihu single-file components; a Rust compiler emits standards-based Web Components plus the machine-readable agent manifest — no separate API layer to build.

Generative UI vs. durable components. Most "agent UI" today is disposable: the model emits HTML or JSON that renders once and vanishes (MCP Apps, generated iframes). Aihu is the inverse — real, inspectable, reusable custom elements an agent drives over a server-mediated capability bridge, with the server holding auth and policy. Durable wins when the UI has to be trusted, styled, and reused.

Under the hood it's a complete meta-framework — routing, SSR, auth, data loading, and cloud adapters included. The runtime is sub-2 kB, output is vanilla custom elements (no lock-in, no hydration step), with zero runtime dependencies, and reactive updates run 122× faster than vanilla DOM on targeted writes (benchmarks below).

Status: actively developed and shipping in v1.0.x releases — the reactive runtime, compiler, router, server, agent surface, CLI, styling engine, and UI primitives all work today. See Project status.

Quickstart

# The agent showcase — a durable <task-list> a human AND an AI agent drive
npx create-aihu my-app --template agent
cd my-app && bun install
bun run dev      # component on http://localhost:5108 · agent bridge on :5208

# …or a minimal app
npx create-aihu my-app

# …or run the canonical examples portfolio in parallel
git clone https://github.com/fellwork/aihu
cd aihu && bun install
bun run dev:examples

For an SFC tour, see examples/live-counter/ (~40 LOC) or jump to the example portfolio.

What it is

You write a component in a single .aihu file — markup, state, styles, and (optionally) its agent interface, all in one place. The compiler turns it into a plain custom element that runs anywhere Web Components run. What you get:

• A tiny reactive core — signals, computeds, and effects in under 2 kB, with direct DOM updates and no virtual DOM (@aihu/signals + @aihu/arbor).
• A real Rust compiler — pre-built per platform, plus a WebAssembly build for in-browser playgrounds.
• Agent-callable by default — declare a component's @agent interface and the compiler emits a matching AI tool schema (MCP), alongside A2A and ACP protocol support.
• A complete app framework — file-based routing, server-side rendering, loaders, cookies, and server actions (@aihu/router + @aihu/server).
• Batteries included — auth, data loading, context, a plugin system, and accessible UI primitives — all dependency-free.
• Deploy anywhere — first-party Cloudflare and Vercel adapters.
• A real toolchain — a CLI for scaffolding and builds (aihu app/page/component/plugin/dev/build) and a VS Code extension.

The output is plain custom elements: nothing locks you in at the consumer boundary, there's no global runtime and no hydration step — and every component is, by construction, callable by an AI agent.

How it compares

Most component libraries give you a way to build components. Aihu gives you a way to build apps — routing, server-side rendering, data, and deployment are first-class, not add-ons.

Aihu is to Lit what Next.js is to React: a full app framework built on a small Web Components runtime. Solid is a single reactive package; Lit is templating plus a base class; Vue ships its own scheduler and virtual DOM. Aihu layers cleanly — use just the signals, just the runtime, or the whole framework — and it's the only one where every component is also an AI-callable tool, built into the file format itself.

Features

Reactive runtime

• Push-based signals, computeds, and effects with batched writes (@aihu/signals, ~1.8 kB gz)
• Direct DOM updates, no virtual DOM (@aihu/arbor, ~2.1 kB gz — 122× faster than vanilla on targeted updates)
• Synchronous mount with predictable teardown
• Compiled components register as standard custom elements (@aihu/runtime)

Compiler & toolchain

• Rust-native compiler — reads .aihu files and emits standard custom-element classes
• Pre-built binaries for Linux, macOS, Windows, and ARM64 Linux (SHA256-verified), via npm install @aihu/compiler
• WebAssembly build for in-browser playgrounds (target: under 200 ms to compile a 50-line component)
• Scoped styles, slots, list/conditional rendering, type-checked templates, error boundaries, hot reload, islands, and full hydration

AI-agent surface (built in)

• An @agent block declares a component's exposed state and actions; the compiler emits a matching MCP tool schema next to the Web Component
• A2A and ACP agent protocols included (@aihu/agent-a2a, @aihu/agent-acp)
• Auto-generates llms.txt, an MCP Server Card, and robots.txt for any app — no manual config (@aihu-plugin/agent-readiness)

Full-stack capabilities

• File-based routing with nested routes and layouts (@aihu/router)
• Server-side rendering, streaming, loaders, cookies, and hydration (@aihu/server)
• Request-scoped context plus a reactive data/loader layer (@aihu/context, @aihu-plugin/data)
• Accessible UI primitives — guards, live regions, focus traps, links, and outlets
• Cloud adapters for Cloudflare and Vercel

Developer experience

• aihu CLI for scaffolding and builds (app / page / component / plugin / dev / build)
• VS Code extension — syntax highlighting today, full language server in progress
• An example portfolio you can run in parallel with bun run dev:examples
• Built on Bun, Rolldown, Biome, and Vitest

Standards & compliance

• llms.txt — every app is discoverable by AI tools out of the box
• MCP — Model Context Protocol compatible (Server Card, tool schemas, resources)
• Agent-ready — every component an app ships has an agent interface
• Accessibility — WCAG-oriented primitives (live regions, focus traps, skip links)

Project status

Aihu is under active development and ships in v1.0.x releases. The reactive runtime, compiler, router, server, agent surface, CLI, styling engine (@aihu/css-engine — a Tailwind v4-style utility engine with scoped, zero-browser-byte output), and accessible UI primitives (@aihu/primitives — dialog, tooltip, button, and more) all work today. The v1.0.0 milestone tag is held for one remaining piece:

• Rich-text / markdown support, shipping as a plugin.

A copy-paste UI registry built on the engine is also in progress.

Packages version independently (most are in the 0.x range during early access), so you can adopt any piece on its own. Aihu is dependency-free at runtime — every browser-shipped package has an empty dependencies list. It's a research-driven codebase: each layer is pinned by a written spec before code lands, and performance regressions block merges.

Migrating between grammar versions is mechanical — run npx aihu migrate <file>, and compiler errors point you at the exact fix. See docs/cli.md for the migration reference.

Performance

All results from bench/. Measured with mitata + Bun 1.3.8. p50 latencies shown. Full tables in bench/signals/RESULTS.md and bench/arbor/RESULTS.md.

@aihu/signals vs SOTA reactive libraries

Source: bench/signals/RESULTS.md. p50 latency shown for each competitor.

@aihu/arbor vs SOTA DOM-binding libraries

Source: bench/arbor/RESULTS.md. JSDOM workloads, p50 latency.

_{Auto-generated — run bun scripts/sync-readme.ts to update.}

The update-1-of-10k-leaves 122× win comes from arbor's leaf() binding to textNode.nodeValue (direct property set) vs. vanilla's element.textContent (child-list walk). This is not a measurement artifact — it reflects the bind-target choice in materialize.ts.

solid-js and @vue/runtime-dom ERROR in all JSDOM workloads (client-only API / SVGElement not defined). Browser-native comparison deferred to Round N+2 Playwright runner.

Bundle size (gz)

Per-package gates enforced by bun run size:

_{Auto-generated — run bun scripts/sync-readme.ts to update.}

Per-package rows are the contract; combined is reported, not budgeted. The pre-v1 "≤ 3.46 kB combined" target was retired at v1 cutover (Plan 7.1) — packages grew to support hydration, islands, error boundaries, and reconciliation. Each row in .size-limit.json is the binding gate. See .size-limit.README.md.

Layout

Publish status: packages publish independently at 0.x early-access (see Project status). A few internal packages stay private until their designs settle.

See packages/ for all packages on disk. By tier:

• Browser runtime (sized, ships to client): @aihu/signals, @aihu/arbor, @aihu/runtime, @aihu/context, @aihu/agent.
• Server / edge / data (sized): @aihu/router, @aihu-plugin/data, @aihu/agent-service, @aihu/agent-acp, @aihu/agent-a2a. Plus @aihu/server (SSR + back-compat router alias), @aihu-plugin/agent-readiness (llms.txt, MCP Server Card, robots, Vite plugin), @aihu/app (top-level integration).
• Cloud adapters (in-tree): @aihu/adapter-cloudflare, @aihu/adapter-vercel.
• Build-time only (not shipped): @aihu/compiler (Rust SFC compiler), @aihu/cli (aihu app, aihu dev, aihu build), @aihu/plugin (plugin contract types).
• Editor: vscode-aihu (TextMate grammar + snippets; Volar LSP in M2).

Packages

_{Auto-generated — run bun scripts/sync-readme.ts to update.}

Examples

13-example portfolio under examples/. Six are M1-polished with full @agent surfaces, dark-mode tokens, and smoke tests:

_{Auto-generated — run bun scripts/sync-readme.ts to update.}

Run all polished examples in parallel:

Toolchain

• Runtime: Bun ≥ 1.3.0, Node ≥ 20.18.0. Both required (engines enforced).
• Bundler: Rolldown — Rust-based, OXC ecosystem.
• Test: Vitest + jsdom + fast-check (property tests).
• Lint/format: Biome.
• Task runner: Moon — moon run :build, moon run :typecheck.
• Size budget: size-limit gates per-package gzipped bundles.
• Tool versions: pinned via proto (.prototools).

Workspace dev loop

bun install
bun run build      # build all packages
bun run test       # TS + Rust suites (unit + integration + compliance)
bun run size       # per-package gzipped bundle gates
bun run check      # biome lint + format
bash scripts/check-boundary.sh   # AC-7: hard boundary (no client imports in server layer)
bash scripts/check-edge-safe.sh  # AC-6: no Node-only globals in dist bundles
bun run test:quality              # Lighthouse gate (≥ 90 on perf/a11y/best-practices/seo)

Run the bench suites:

cd bench/signals && bun src/runner.ts   # signals vs SOTA
cd bench/arbor   && bun src/runner.ts   # arbor vs SOTA (JSDOM)

Use the packages directly:

import { signal, computed, effect } from '@aihu/signals'
import { branch, leaf, mount } from '@aihu/arbor'
import { defineComponent } from '@aihu/runtime'
import { registerAgentMetadata } from '@aihu/agent'

const [count, setCount] = signal(0)
const tree = branch('div', null, [leaf([count, setCount])])
const scope = mount(tree, document.body)
setCount(1) // DOM updates synchronously via nodeValue
scope.dispose()

Edge / server (fetch-API, works on Cloudflare Workers, Deno, Bun) — request-router shape from @aihu/server. Two distinct routing APIs ship in aihu: @aihu/server.createRequestRouter builds a fetch-API request handler from an explicit route manifest (shown below), while @aihu/router.createRouter powers file-based routing via the v1 Vite plugin (viteRouterPlugin); see docs/site/routing-layouts.md.

import { createRequestRouter, defineRoute, json } from '@aihu/server'
import { createAgentReadinessRoutes } from '@aihu-plugin/agent-readiness'

const ar = createAgentReadinessRoutes({
  name: 'My App',
  endpoint: 'https://myapp.workers.dev/mcp',
  summary: 'A aihu-powered app.',
})

const router = createRequestRouter({
  routes: [
    defineRoute('/llms.txt', ar.llmsTxt),
    defineRoute('/.well-known/mcp/server-card.json', ar.mcpServerCard),
    defineRoute('/robots.txt', ar.robotsTxt),
    defineRoute('/api/hello', () => json({ hello: 'world' })),
  ],
})

// Cloudflare Worker
export default { fetch: router }
// Deno / Bun
// Deno.serve(router)  |  Bun.serve({ fetch: router })

Compliance

The agent-protocol badges are backed by real test gates in bun run test.

Run all compliance checks: bun run test && bun run test:quality

Reference

• User guide — docs/site/: introduction, installation, getting started, authoring components, authoring agents, reactivity, SSR + hydration, routing + layouts, data fetching, deployment, API reference, and plugins.
• CLI reference — docs/cli.md: create-aihu, aihu app / page / component / dev / build, and aihu migrate.
• Contributing — CONTRIBUTING.md: fork, branch, conventional commits, changesets, and the dependency-free thesis.
• Releasing — docs/RELEASING.md: changeset workflow, release PR, npm publish pipeline.
• Benchmarks — bench/signals/ and bench/arbor/: harness + full results.

License

MIT