convez.ai
MCP ServerDesenvolvimento WebAvançado
fellwork

Aihu — Web Components Duráveis para Agentes IA

fellwork/aihu

Componentes reais que agentes controlam, não UI gerada que desaparece

Ver no GitHub
BomPluginScore · de 0 a 100

Framework meta-completo que compila componentes Web duráveis (não descartáveis) que agentes de IA podem inspecionar e controlar via MCP + llms.txt. Você escreve SFCs em `.aihu`, o compilador Rust emite custom elements padrão com manifest legível por máquina, eliminando a necessidade de gerar UI descartável a cada turno.

Instalação

$npx convez-ai fellwork/aihu

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 1 semana
Versão
v0.4.72
Issues abertas
32
Contribuidores
4

Casos de uso

  • Interfaces de agentes IA que precisam ser duráveis e reutilizáveis
  • Componentes Web com capacidades inspecionáveis por IA
  • Aplicações que integram agentes Claude com UI confiável e reusável

Veredito

Abordagem inovadora que inverte o paradigma de UI generativa — Web Components reais e inspecionáveis em vez de HTML descartável. Excelente para arquiteturas onde agentes precisam dirigir interfaces confiáveis, com runtime mínimo (sub-2 kB) e compatibilidade total com MCP. Nicho bem-definido, tecnicamente sólido.

README

A tradução para o português deste README ainda está na fila.

Aihu

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.

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, shipping in v1.0.x releases. The v1.0.0 milestone tag is held until the styling engine and UI components land — see Project status.

CI release @aihu/signals on npm tests packages llms.txt MCP Agent Ready


Quickstart

# Scaffold a new app
bunx @aihu/cli app my-app
cd my-app
bun install
bun run dev      # http://localhost:5173

# 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 13-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
  • A 13-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, and CLI all work today. The v1.0.0 milestone tag is intentionally held until three additions land:

  • A styling engine (@aihu/css-engine) — build-time CSS: a Tailwind v4-style utility engine with scoped, per-component output that adds zero bytes to the browser bundle. The engine, compiler integration, style packs, and a cn() helper have landed; a copy-paste UI registry is next.
  • UI components (@aihu/primitives) — accessible, headless primitives (dialog, tooltip, button, and more) built on the engine. Landed.
  • Rich-text / markdown support, shipping as a plugin.

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.

Workload@aihu/signalsalien-signals@preact/signals-core@vue/reactivitysolid-jss-js
cellx807.33 ns1.21 µs1.14 µs1.69 µs2.97 µs1.40 µs
batched-writes-1005.07 µs8.10 µs7.20 µs15.43 µs12.80 µs5.75 µs
dynamic-deps1.09 µs2.78 µs1.78 µs7.08 µs1.93 µs1.33 µs
creation-1to100069.02 µs90.01 µs64.53 µs92.97 µs139.98 µs107.53 µs
deep-propagation-1003.25 µs3.97 µs3.87 µs7.34 µs11.86 µs4.12 µs

@aihu/arbor vs SOTA DOM-binding libraries

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

Workload@aihu/arborlit-htmlsolid-js@vue/runtime-dompreactvanilla
mount-10k-leaves49.04 ms8.21 s——107.10 ms139.42 ms
mount-deep-100x104.32 ms82.33 ms——12.32 ms28.92 ms
mount-wide-100012.69 ms92.01 ms——14.78 ms17.38 ms
update-1-of-10k-leaves28.63 ns743.62 µs——2.33 ms4.36 µs
krausest-1k-cycle31.16 ms114.20 ms——30.71 ms25.17 ms

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:

PackageSize (gz)LimitStatus
@aihu/context242 B300 Bpass
@aihu/signals1.69 kB1970 Bpass
@aihu/arbor2.60 kB2800 Bpass
@aihu/runtime3.73 kB3900 Bpass
@aihu/agent141 B200 Bpass
@aihu-plugin/data757 B800 Bpass
@aihu-plugin/kindly-note1.65 kB1850 Bpass
@aihu/router1.71 kB2400 Bpass
@aihu/agent-service1.17 kB1400 Bpass
@aihu/agent-acp586 B600 Bpass
@aihu/agent-a2a717 B750 Bpass
@aihu/app1.58 kB1750 Bpass
@aihu/css-engine/runtime/cn886 B1 KBpass
@aihu/css-engine/runtime/progressive716 B3 KBpass
@aihu/primitives/context430 B1 KBpass
@aihu/primitives/presence-gate798 B4 KBpass
@aihu/primitives/form-control1.32 kB4 KBpass
@aihu/primitives/config-provider757 B4 KBpass
@aihu/primitives/roving-focus1.41 kB4 KBpass
@aihu/primitives/collection515 B4 KBpass
@aihu/primitives/dialog2.01 kB4 KBpass
@aihu/primitives/tooltip1.83 kB4 KBpass
@aihu/primitives/button1.10 kB4 KBpass
@aihu/primitives/separator566 B4 KBpass
@aihu/primitives/label1.77 kB4 KBpass
@aihu/primitives/input1.43 kB4 KBpass
@aihu/primitives/textarea1.41 kB4 KBpass
@aihu/primitives/checkbox1.76 kB4 KBpass
@aihu/primitives/switch1.67 kB4 KBpass
@aihu/primitives/radio-group2.91 kB4 KBpass
@aihu/auth1.16 kB1.5 KBpass
@aihu/magna758 B1.8 KBpass
@aihu/magna/codegen1.04 kB1.2 KBpass

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

PackageVersionDescription
@aihu-plugin/agent-readiness2.0.4Discovery + readiness manifest emitter so agents can introspect aihu apps.
@aihu-plugin/data2.0.1Reactive data loaders and resource primitives for aihu.
@aihu-plugin/drizzle0.1.1Drizzle ORM data adapter for aihu — typed createResource fetchers and defineLoader helpers (Postgres / SQLite / libSQL).
@aihu-plugin/kindly-note0.2.1Runtime syntax highlighting + markdown rendering for aihu — / custom elements + signal-aware highlight()/renderMarkdown() helpers, powered by published @kindly-note/* packages with lazy loading.
@aihu/adapter-cloudflare4.0.1Cloudflare Workers/Pages deployment adapter for @aihu/app.
@aihu/adapter-vercel4.0.1Vercel deployment adapter for @aihu/app.
@aihu/agent0.1.0Agent primitives — the foundation of aihu agent-readiness.
@aihu/agent-a2a0.1.2A2A (Agent-to-Agent) protocol bindings for @aihu/agent-service.
@aihu/agent-acp0.1.2ACP (Agent Control Protocol) bindings for @aihu/agent-service.
@aihu/agent-readiness2.0.2[MOVED] This package has moved to @aihu-plugin/agent-readiness.
@aihu/agent-server0.2.0Server-side glue: mount an aihu component server-side and let an MCP client drive it through the agent-service live-dispatch gate, forwarding approved invocations to a browser bridge.
@aihu/agent-service0.2.0Service-side agent runtime (server-hosted agent endpoints).
@aihu/ai0.1.0Thin adapters from AI SDK stream types to ReadableStream for aihu $stream collections.
@aihu/app3.0.1Top-level app integration — wires runtime, router, and adapters into a Vite app.
@aihu/arbor1.0.0Reactive component tree (the rendering layer that consumes @aihu/signals).
@aihu/auth1.0.0JWT scope checks, ScopeSignal, and server middleware for aihu auth.
@aihu/cli0.6.0Aihu CLI (aihu, create-aihu) — scaffolding, dev, build commands.
@aihu/compiler0.9.1Single File Component (.aihu) compiler — Rust binary + JS glue.
@aihu/context0.1.0Async-context-friendly request/SSR context primitives for aihu.
@aihu/css-engine0.4.3aihu CSS engine — Tailwind v4 hard fork with WC-native scoped output.
@aihu/data2.0.1[MOVED] This package has moved to @aihu-plugin/data.
@aihu/language-server0.2.9Cross-editor Language Server (aihu-language-server) for .aihu Single File Components — diagnostics, hover, completion, and quick-fix code actions.
@aihu/magna0.2.1aihu bridge for Magna GraphQL — dep-free fetch, resource composition, JWT relay
@aihu/mcp0.1.0MCP server for aihu — exposes aihu_example and aihu_validate tools via stdio transport.
@aihu/plugin0.1.0Plugin substrate shared by @aihu/server and the meta-framework — runtime hook surface.
@aihu/plugin-demo0.1.1Canonical proof-of-life for the @aihu/plugin API — exercises macros, middleware, and transforms.
@aihu/primitives0.1.0aihu headless behavior primitives — WAI-ARIA APG patterns as vanilla custom elements, zero CSS.
@aihu/router0.2.2File-based router for the aihu meta-framework.
@aihu/runtime1.1.0Single File Component (.aihu) runtime — registers custom elements compiled by @aihu/compiler.
@aihu/scraping0.1.0O(1) sliding-window rate limiter and bot-detection middleware for aihu agent services.
@aihu/seo0.2.1aihu SEO plugin: sitemap.xml, robots.txt, llms.txt, JSON-LD injection via afterParse hook.
@aihu/server0.2.1Server runtime + native renderer (napi-rs) for aihu SSR.
@aihu/signals0.2.0Tiny reactive signals — the reactive primitive at the core of aihu.
@aihu/templates-cf-team3.0.1Cloudflare Workers + monorepo (bun workspaces + moon) team template for Aihu
@aihu/ui0.1.0aihu styled-recipe registry — copy-paste .aihu recipes distributed as source via aihu add (no runtime bundle).
vscode-aihu1.0.0Syntax highlighting, snippets, and language support for .aihu Single File Components

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:

#FolderWhat it teachesPort
01agent-driven-demo/An external agent reads a component's metadata and drives the real, visible component instance over a real WebSocket — gated server-s...5108
02agent-hub/no README5107
03auth-magna-seo/A server-only worked example that proves the 3-package integration contract — @aihu/auth + @aihu/magna + @aihu/seo — using **on...—
04blog-loader/A server-rendered post page demonstrating aihu's loader pattern, @aihu/context as a parallel data channel, and an @agent block for ag...—
05blog-router/A 3-page blog demonstrating aihu's file-based routing.—
06cf-adapter/no README5110
07color-theme/$reactive(...) in @style plus $global { } to propagate tokens beyond component scope — and $media macro for responsive breakpoint...5105
08css-engine-demo/Demonstrates all three browser-facing surfaces of the published @aihu/css-engine package:5114
09css-engine-utility/When @aihu/css-engine is installed (as a dependency or peer), the compiler plugin that viteAihuPlugin composes will:5118
10css-pluggability/A worked example showing how to plug Tailwind CSS into a aihu app, plus documented swap paths to UnoCSS, Pico CSS, and **vani...—
11currency-converter/the second @agent flagship, with enum-typed inputs. Demonstrates how a TypeScript union type (`'USD''EUR'
12hacker-news/A aihu port of the canonical Hacker News reader. Hits the live HN API. M1 polish: dark-mode token pass, @agent block on the index page,...5108
13layouts/Runtime layout rendering + dynamic layout switching.—
14live-counter/the smallest possible aihu component — state, event handlers, a reactive text node, and an agent surface, in one file.5101
15plugin-demo/no README5111
16primitives-showcase/Wires three WAI-ARIA APG patterns from the published @aihu/primitives package — each a vanilla custom elem...5115
17realtime-scores/Live score board demonstrating WebSocket-driven signal updates, $lifecycle.mount/dispose, and createResource from @aihu-plugin/data...5112
18storefront/no README5113
19temperature-converter/two-way binding plus a computed-derived counterpart (7GUIs #2), and an agent surface that lets AI tools read and write the temperature on...5102
20timer/lifecycle hooks, reactive derivations, and an agent surface that lets AI monitor timer progress and trigger resets on the human's behalf ...5103
21todo-mvc/the canonical TodoMVC — list reactivity, filtering, computed derivations, keyed iteration, localStorage persistence, and an agent surface...5104
22weather-card/the aihu-unique @agent block. Every signal you $expose becomes an MCP resource; every action you $action becomes an MCP tool. The s...5106

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

Run all polished examples in parallel:

bun run dev:examples

The remaining examples ship in M2.


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       # 607 TS tests + 222 Rust tests (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.

GateTestsStatus
llms.txt format (llmstxt.org spec)9 tests in packages/plugin-agent-readiness/tests/compliance/llms-txt-spec.test.tspassing
MCP Server Card schema (SEP-1649)14 tests in packages/plugin-agent-readiness/tests/compliance/mcp-server-card-schema.test.tspassing
robots.txt RFC 93097 tests in packages/plugin-agent-readiness/tests/compliance/robots-rfc9309.test.tspassing
isitagentready.com endpoint checklist7 tests in packages/plugin-agent-readiness/tests/compliance/isitagentready.test.tspassing
SSR output structural checks12 tests in packages/server/tests/compliance/ssr-output.test.tspassing
Lighthouse quality gate (≥ 90 all categories)bun run test:quality via scripts/lighthouse.tspassing

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


Reference

Architecture tracks

Roadmap tracks

Specs (ratified + RFC)

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

Process docs

  • CONTRIBUTING.md — fork, branch, conventional-commits, changesets, dep-free thesis.
  • docs/RELEASING.md — changeset workflow, release PR, npm publish pipeline.
  • docs/site/ — 12-page user guide: introduction, installation, getting-started, authoring-components, authoring-agents, reactivity, ssr-hydration, routing-layouts, data-fetching, deployment, api-reference, authoring-plugins.
  • docs/cli.md — CLI reference.
  • CLI: @aihu/cli — npx aihu app, npx aihu migrate.

Pre-v1 phase specs (historical, still binding)

Bench harness


License

MIT

Ver o original no GitHub

Bom para

Relacionados