Building Persistent AI-Ready Web Components with Aihu

Aihu is a meta-framework designed to build web components that serve two distinct audiences: human users and AI agents. By authoring a single .aihu file, developers can define a reactive UI and an MCP (Model Context Protocol) tool surface simultaneously. This approach ensures that the interface remains consistent for both users, preventing the drift often found when maintaining separate UI and API layers. Aihu components persist and hold their own state, allowing agents to steer the same interface the user sees.

Core Concepts and Workflow

The framework operates on the principle of equal governance. When you define state or actions within a component, you can mark them with expose. The Aihu compiler then automatically generates the corresponding MCP tool schema. This means that an agent can only interact with the specific parts of your component that you have explicitly exposed, with entitlement resolved server-side. Nothing is agent-reachable unless you explicitly declare it.

To start a new project, use the provided CLI:

npx create-aihu my-app --template agent

This command scaffolds an application where the component is ready for both human interaction and agent-driven tasks. The framework uses a Rust-based compiler to emit standard custom elements, ensuring that the output is compatible with modern browsers without requiring a virtual DOM or complex hydration steps. The output is vanilla custom elements with zero runtime dependencies.

Component Structure

A typical .aihu component integrates state, view, styles, and the agent interface into one file. Consider this example of a live counter:

@state { let count = state(0) const increment = action( { describe: 'Add 1 to the counter', expose: 'read write' }, () => { count = count + 1 }) const reset = action( { describe: 'Reset the counter to 0', expose: 'read write' }, () => { count = 0 }) } @template { <section class="counter"> <h1>Count: {count}</h1> <button on:click={reset}>Reset</button> <button on:click={increment}>+</button> </section> } @style { .counter { display: grid; gap: 0.75rem; } }

In this structure, state(0) declares a reactive field, and action defines methods that are accessible to both the UI and AI agents. Because the agent interface is derived from the same declaration as the UI, the agent steers the actual component instance rather than fabricating a temporary interface. The template uses prefix-less HTML with {expr} for reactive values and on:click for events.

Technical Capabilities

Aihu provides a full-stack environment, including:

• Reactive Runtime: A sub-2 kB core (@aihu/signals and @aihu/arbor) that performs direct DOM updates without a virtual DOM. Targeted text writes land on a cached text node.
• Full-Stack Framework: Includes file-based routing (@aihu/router), server-side rendering, streaming, loaders, cookies, and server actions.
• Agent Readiness: Automatic generation of llms.txt, MCP Server Cards, and A2A protocol support.
• Deployment: First-party adapters for Cloudflare and Vercel.
• Toolchain: A Rust-native compiler with pre-built binaries for Linux, macOS, Windows, and ARM64 Linux, plus a WebAssembly build for in-browser playgrounds.

Developer Experience and Ecosystem

Aihu is designed to be a complete meta-framework. It includes a CLI for scaffolding and builds, and a VS Code extension for syntax highlighting. The framework is dependency-free at runtime, meaning every browser-shipped package has an empty dependencies list. Developers can adopt individual pieces of the framework, such as just the signals or the runtime, or use the entire stack for full-app development.

The framework is built on modern web standards and tools, including Bun, Rolldown, Biome, and Vitest. It provides accessible UI primitives, such as dialogs, tooltips, and buttons, which are WCAG-oriented. The styling engine, @aihu/css-engine, provides scoped, zero-browser-byte output similar to Tailwind v4.

Limitations and Considerations

Aihu is currently in active development with v1.0.x releases. While the core reactive runtime, compiler, and agent surface are functional, some features like rich-text and markdown support are currently being implemented as plugins. The framework is designed for developers who want to build durable, persistent interfaces that AI agents can reliably interact with over time. It is not intended for scenarios where UI components are expected to be ephemeral or generated on-the-fly without state persistence. Aihu is a research-driven codebase where each layer is pinned by a written spec before code lands, and performance regressions block merges. For further details on the project status and to explore the component registry, visit the official repository at https://github.com/fellwork/aihu.