# Architecture URL: /docs/architecture How components, runtimes, and cloud services fit together. > For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths. ## assistant-ui is built on these main pillars: - 1\. Frontend components — Shadcn UI chat components with built-in state management - 2\. Runtime — State management layer connecting UI to LLMs and backend services - 3\. Assistant Cloud — Hosted service for thread persistence, history, and user management ### 1. Frontend components Styled chat components built on top of shadcn/ui components. They read their state from the assistant-ui runtime provider. [View our components](/elements/thread) ### 2. Runtime A React state management context for assistant chat. The runtime handles data conversions between the local state and calls to backends and LLMs. Runtimes are available for frameworks like Vercel AI SDK, LangGraph, and LangChain, along with a local runtime and an ExternalStore runtime for when you need full control of the frontend message state. [You can view the runtimes we support](/docs/runtimes/pick-a-runtime) ### 3. Assistant Cloud A hosted service for thread management and message history. Assistant Cloud stores complete message history, automatically persists threads, supports human-in-the-loop workflows, and integrates with common auth providers so users can resume conversations at any point. [Cloud Docs](/docs/cloud) ## What each layer owns Before picking a runtime or wiring components, it helps to see which layer owns which responsibility. assistant-ui draws hard lines between rendering, conversation state, and where the model actually runs. ### UI layer Primitives and prebuilt components render the assistant experience: thread, messages, composer, message parts, actions, attachments, suggestions. They read and write through the runtime context, not directly against the backend or model. ### Runtime layer The state and behavior boundary between UI and backend. The runtime owns or adapts conversation state: messages, thread state, composer state, run lifecycle, branching, editing, regeneration. Different runtimes exist because different backends own this state differently. `LocalRuntime` keeps state internal; `ExternalStoreRuntime` delegates to your store. ### Backend / agent layer Produces assistant output and app-specific behavior. Depending on the runtime and protocol, the backend may emit text, message parts, tool calls, metadata, agent state, attachments, or other events that the runtime maps into UI state. ### Integration / protocol layer Runtime adapters and protocols bridge assistant-ui to different backend shapes: AI SDK, LangGraph, LangChain, ADK, A2A, AG-UI, OpenCode, or your own. The DataStream and AssistantTransport protocols let a generic backend talk to assistant-ui without a custom adapter per app. ### Persistence layer Thread and message history can be stored by Assistant Cloud or by your own database via thread and history adapters. Persistence is separate from rendering and backend generation, though the runtime coordinates with it. ## There are three common ways to architect your assistant-ui application: #### **1. Direct Integration with External Providers** ```mermaid graph TD A[Frontend Components] --> B[Runtime] B --> D[External Providers or LLM APIs] ``` #### **2. Using your own API endpoint** ```mermaid graph TD A[Frontend Components] --> B[Runtime] B --> E[Your API Backend] E --> D[External Providers or LLM APIs] ``` #### **3. With Assistant Cloud** ```mermaid graph TD A[Frontend Components] --> B[Runtime] B --> C[Cloud] E --> C C --> D[External Providers or LLM APIs] B --> E[Your API Backend] ``` ## Going deeper These pages go one level deeper on runtime internals, adapters, and persistence. - [Runtime architecture](/docs/runtimes/concepts/architecture) — Core runtimes, protocol layers, framework adapters, and what each layer owns. - [Adapters](/docs/runtimes/concepts/adapters) — Attachments, speech, feedback, history, suggestions across runtimes. - [Threads](/docs/runtimes/concepts/threads) — Multi-thread support: cloud, custom database, ExternalStore. # Overview URL: /docs Components, runtimes, and primitives for building AI chat interfaces in React, Vue, React Native, and the terminal. > For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths. Ask your coding agent to `install and set up assistant-ui`. When the user asks you to "install and set up assistant-ui" (or "set up assistant-ui"), run `npx assistant-ui@latest setup`. Run it in the background and read its output: it keeps running as the guided setup's stream and opens the user's browser when it needs their input. If `setup` isn't a known command (a cached or pnpm release-age-gated version), run `npx -y --prefer-online assistant-ui@latest setup` instead. To install by hand, follow the [manual installation guide](/docs/manual-installation). ## Pick a surface Same primitives on web, native, and the terminal. - [React](/docs/installation): Web chat interfaces - [React Native](/docs/react-native): iOS and Android - [React Ink](/docs/ink): Terminal apps - [Vue](/docs/vue): Vue and Nuxt apps ## Bring your own backend A runtime connects these components to your AI backend. Pick the one that matches your stack. - [Vercel AI SDK](/docs/runtimes/ai-sdk/overview) - [LangGraph](/docs/runtimes/langgraph/overview) - [LangChain](/docs/runtimes/langchain) - [Eve](/docs/runtimes/eve/overview) - [Google ADK](/docs/runtimes/google-adk/overview) - [AG-UI](/docs/runtimes/ag-ui/overview) - [A2A](/docs/runtimes/a2a/overview) - [OpenCode](/docs/runtimes/opencode/overview) - [Your own server](/docs/runtimes/custom/overview) - [Compare all](/docs/runtimes/pick-a-runtime) ## Everything else - Build: [Primitives](/docs/primitives) - Build: [Components](/elements/thread) - Build: [Tool UI](/docs/tools/tool-ui) - Build: [Generative UI](/docs/tools/generative-ui) - Build: [MCP servers](/docs/tools/mcp) - Build: [API reference](/docs/api-reference/overview) * Guides: [Attachments](/docs/guides/attachments) * Guides: [Branching](/docs/guides/branching) * Guides: [Voice](/docs/guides/voice) * Guides: [Persistence](/docs/cloud) * Guides: [Migrations](/docs/migrations) - Explore: [Agent skills](/docs/llm) - Explore: [Examples](/examples) - Explore: [Design](/design) # Agent Skills URL: /docs/llm Use AI tools to build with assistant-ui faster. AI-accessible documentation, Claude Code skills, and MCP integration. > For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths. This page covers the ways to give your AI tools access to assistant-ui documentation and context. ## AI Accessible Documentation The docs are available in formats that AI assistants can read: - [/llms.txt](/llms.txt) — Structured index of all documentation pages. Point your AI here for a quick overview. - [/llms-full.txt](/llms-full.txt) — Complete documentation in a single file. Use this for full context. - .mdx suffix — Add `.mdx` to any page's URL to get raw markdown content (e.g., `/docs/installation.mdx`). ### Context Files Add assistant-ui context to your project's `CLAUDE.md` or `.cursorrules`: ``` ## assistant-ui This project uses assistant-ui for chat interfaces. Documentation: https://www.assistant-ui.com/llms-full.txt Key patterns: - Use AssistantRuntimeProvider at the app root - Thread component for full chat interface - AssistantModal for floating chat widget - useChatRuntime hook with AI SDK transport ``` ## Skills Install assistant-ui skills for AI Tools: ``` npx skills add assistant-ui/skills ``` | Skill | Purpose | | --------------- | -------------------------------------------------------------------- | | `/assistant-ui` | General architecture and overview guide | | `/setup` | Project setup and configuration (AI SDK, LangGraph, custom backends) | | `/primitives` | UI component primitives (Thread, Composer, Message, etc.) | | `/runtime` | Runtime system and state management | | `/tools` | Tool registration and tool UI | | `/streaming` | Streaming protocol with assistant-stream | | `/cloud` | Cloud persistence and authorization | | `/thread-list` | Multi-thread management | | `/update` | Update assistant-ui and AI SDK to latest versions | Use by typing the command in Claude Code, e.g., `/assistant-ui` for the main guide or `/setup` when setting up a project. ## MCP assistant-ui hosts an MCP server at `https://www.assistant-ui.com/mcp` (Streamable HTTP). It serves the live documentation, examples, design components, and Tap docs, and exposes the hosted app templates. There is nothing to install and it is always current. Once connected, your AI assistant can look up the assistant-ui documentation while it works. For example, ask: - "Add a chat interface with streaming support to my app" - "How do I integrate assistant-ui with the Vercel AI SDK?" - "My Thread component isn't updating, what could be wrong?" ### Quick Install For Claude Code: ``` claude mcp add --transport http assistant-ui https://www.assistant-ui.com/mcp ``` For other IDEs, the assistant-ui CLI configures the right client for you: ``` npx assistant-ui@latest mcp ``` ### Manual Installation Choose one: **Cursor** [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=assistant-ui\&config=eyJ1cmwiOiJodHRwczovL3d3dy5hc3Npc3RhbnQtdWkuY29tL21jcCJ9) Or add to `.cursor/mcp.json`: ``` { "mcpServers": { "assistant-ui": { "url": "https://www.assistant-ui.com/mcp" } } } ``` After adding, open Cursor Settings → MCP → find "assistant-ui" and click enable. **Windsurf** Add to `~/.codeium/windsurf/mcp_config.json`: ``` { "mcpServers": { "assistant-ui": { "serverUrl": "https://www.assistant-ui.com/mcp" } } } ``` After adding, fully quit and re-open Windsurf. **VSCode** Add to `.vscode/mcp.json` in your project: ``` { "servers": { "assistant-ui": { "type": "http", "url": "https://www.assistant-ui.com/mcp" } } } ``` Enable MCP in Settings → search "MCP" → enable "Chat > MCP". Use GitHub Copilot Chat in Agent mode. **Zed** Zed launches MCP servers as local commands, so use the stdio package. Add to your Zed settings file: - macOS: `~/.config/zed/settings.json` - Linux: `~/.config/zed/settings.json` - Windows: `%APPDATA%\Zed\settings.json` ``` { "context_servers": { "assistant-ui": { "command": { "path": "npx", "args": ["-y", "@assistant-ui/mcp-docs-server"] } } } } ``` The server starts automatically with the Assistant Panel. **Claude Code** ``` claude mcp add --transport http assistant-ui https://www.assistant-ui.com/mcp ``` The server is available immediately once added. **Claude Desktop** Claude Desktop's configuration file only supports local commands, so use the stdio package. Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ``` { "mcpServers": { "assistant-ui": { "command": "npx", "args": ["-y", "@assistant-ui/mcp-docs-server"] } } } ``` Restart Claude Desktop after updating the configuration. ### Available Tools | Tool | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `list_pages` | List documentation pages, optionally filtered by a path prefix such as `/docs/tools` or `/examples` | | `get_navigation` | Return the docs navigation tree | | `search_docs` | Search docs, examples, design components, elements, and Tap docs over page content as well as metadata, with an excerpt per result that has body prose | | `read_page` | Read one page as markdown by slug, path, or URL | | `list_templates` | List the hosted app templates and fixed demos | | `read_template` | Get a template's full authoring surface: config schemas, rules, and an example config | | `preview_template` | Create a configured preview session and return preview and download URLs | The server also exposes every page as an MCP resource (`assistant-ui://{path}`) and an `assistant-ui-template-workflow` prompt for template-driven app building. ### Local stdio Server `@assistant-ui/mcp-docs-server` stays published for clients that only launch local stdio servers. It is a thin proxy to the hosted endpoint, so it serves the same live content: ``` npx add-mcp @assistant-ui/mcp-docs-server ``` ### Troubleshooting - **Connection failing**: The hosted server requires network access. Check that the URL is exactly `https://www.assistant-ui.com/mcp` and that your client supports Streamable HTTP. - **Stdio server not starting**: Ensure `npx` is installed and working, then restart the MCP server and your IDE. # Radix UI and Base UI URL: /docs/base-ui How the assistant-ui component registry serves Radix UI and Base UI flavored components for every shadcn style. > For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths. shadcn/ui ships every component for two headless libraries, Radix UI and Base UI. `npx shadcn init` defaults new projects to Base UI styles as of July 2026. Style names that start with `base-`, such as `base-nova`, select the Base UI flavor; every other style name selects Radix. ## Component registry assistant-ui's component registry serves both flavors from the same host. Configure the style-aware URL in `components.json`: ``` { "registries": { "@assistant-ui": "https://r.assistant-ui.com/styles/{style}/{name}.json" } } ``` The shadcn CLI fills `{style}` from your `components.json` `style` field. Styles whose name starts with `base-` receive Base UI flavored components; all other styles receive the Radix flavored ones. The plain `https://r.assistant-ui.com/{name}.json` form remains available as a Radix fallback. ## How compatibility works assistant-ui's headless primitives, the components exported from `@assistant-ui/react`, accept both composition conventions: Radix's `asChild` prop and Base UI's `render` prop. Most registry components only compose these primitives, so a single implementation renders correctly under either flavor and the registry has no need for a separate variant. Open-state styling and panel-height animation do not force a variant either: the kit styles state through custom variants that match both libraries' data attributes, and animates collapsibles through keyframes that read both libraries' height variables, so components like `reasoning`, `tool-group`, and `tool-fallback` serve one source to both flavors. Components that reach past composition into library-specific surfaces (raw primitive imports, trigger composition, provider wiring, popup recomposition) ship a dedicated Base UI variant instead. The following components currently have one: `tooltip-icon-button`, `attachment`, `context-display`, `message-timing`, `mcp-config`, `threadlist-sidebar`, `assistant-modal`, `select`, `tabs`, `accordion`, `badge`, `model-selector`, and `direction`. ## Behavior notes Under Base UI styles, the assistant modal composes the project's Base UI popover, so stacked layers (an attachment preview dialog, a tooltip, and the modal itself) close one layer per Escape key press, with focus restored to the element that opened the closed layer. Clicking outside the modal keeps it open, matching the Radix flavor's behavior. ## FAQ - **Do I need to change anything on an existing Radix project?** No. The plain `https://r.assistant-ui.com/{name}.json` URL keeps resolving to Radix flavored components, so an existing setup needs no changes. - **What happens if I switch styles later?** Re-add the components you use through the shadcn CLI. The style-aware URL resolves the correct flavor for the new style, and no other migration step is required. - **Does `@assistant-ui/react` behave differently under Base UI?** No. The headless `@assistant-ui/react` package works identically in both worlds; only the registry components under `components/assistant-ui` differ by flavor. # CLI URL: /docs/cli Scaffold projects, add components, and manage updates from the command line. > For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths. Use the `assistant-ui` CLI to set up new projects and add components to existing ones. ## setup Use the `setup` command to have your coding agent install assistant-ui, with a guided setup in your browser. ``` npx assistant-ui@latest setup ``` Run by a coding agent, it starts the setup, prints the steps the agent follows, and keeps running as the setup's stream, so agents run it in the background. It opens setup.assistant-ui.com in your browser only when the agent needs your input: a question, the plan to approve, or the finished install. The agent asks its questions there, proposes a plan for you to approve, and shows each install step as it works. Tell any agent this to start: ``` install and set up assistant-ui ``` Run in an interactive terminal, it asks which coding agent you use and starts it in the current directory with that prompt. For an agent it cannot start, it shows the prompt and copies it when you press Enter; without a clipboard tool, copy it from the terminal. The browser asks you to confirm the agent and its directory before it connects. If you close a connected tab, setup opens it again for a later question. It never opens a second tab within 30 seconds of the last, or while a tab it opened has not connected; the agent then asks you in its own chat, and your answer there works the same as one in the browser. The agent runs the other setup commands as `npx assistant-ui@latest setup `, for example `ask`, `plan`, `answer` and `done`. `setup stream` resumes the stream if it stopped. Coding agents use `setup`. Run by a coding agent outside a setup session, `init`, `create` and `add` stop with exit code 2 and point it to `setup`. Inside a setup session, when the folder they act on (`--cwd`, or the project directory given to `init` or `create`) is the folder `setup` runs in or a folder inside it, they run as usual, so the steps the setup gives the agent keep working. A setup session ends when `setup` exits, or two hours after it starts. To run them under an agent anyway, pass `--force` or set `ASSISTANT_UI_ALLOW_AGENT=1`. People in a terminal and CI see no change. **Options** ``` Usage: assistant-ui setup [options] [url-and-command...] set up assistant-ui with your coding agent, guided in your browser Arguments: url-and-command a setup command for the agent: [args], such as ask, answer or stream Options: --products comma-separated catalog slugs to set up (default: assistant-ui) --no-open never open the browser; the agent asks the user in its own conversation -h, --help display help for command ``` ## init Use the `init` command to add assistant-ui to an existing project. ``` npx assistant-ui@latest init ``` This will: - Exit with a notice if the project already has a `components.json` - Run `create` instead if the directory has no `package.json` - Run `shadcn init` to configure the project - Use `shadcn add` to install the assistant-ui quick-start component - Add the default assistant-ui components (thread, composer, etc.) to your project When `init` sets up an existing project in a non-interactive shell such as CI, pass `--yes`. Without it, `init` exits with an error because it cannot prompt. **When to use:** - Adding assistant-ui to an **existing** Next.js project - First-time setup in a project with `package.json` **Options** ``` Usage: assistant-ui init [options] [project-directory] initialize assistant-ui in an existing project Arguments: project-directory directory for the new project Options: -y, --yes skip confirmation prompt. (default: false) -o, --overwrite overwrite existing files. (default: false) -c, --cwd the working directory. defaults to the current directory. --use-npm explicitly use npm --use-pnpm explicitly use pnpm --use-yarn explicitly use yarn --use-bun explicitly use bun --skip-install skip installing packages -h, --help display help for command ``` ## create Use the `create` command to scaffold a new Next.js project with assistant-ui pre-configured. ``` npx assistant-ui@latest create [project-directory] ``` This command scaffolds a project from assistant-ui starter templates or examples. **Available Templates** | Template | Description | Command | | --------------- | ----------------------------------------------------------- | -------------------------------------------- | | `default` | Default template with Vercel AI SDK | `npx assistant-ui create` | | `minimal` | Bare-bones starting point | `npx assistant-ui create -t minimal` | | `cloud` | Cloud-backed persistence starter | `npx assistant-ui create -t cloud` | | `cloud-clerk` | Cloud-backed starter with Clerk auth | `npx assistant-ui create -t cloud-clerk` | | `cloud-harness` | A hosted harness with a shared conversation across browsers | `npx assistant-ui@latest cloud setup my-app` | | `langchain` | LangGraph starter with the react-langchain adapter | `npx assistant-ui create -t langchain` | | `mcp` | MCP tools + MCP Apps renderer starter | `npx assistant-ui create -t mcp` | | `eve` | Eve agent + Next.js starter | `npx assistant-ui create -t eve` | | `vscode` | VS Code extension with a chat webview | `npx assistant-ui create -t vscode` | **Available Examples** Use `--example` to create a project from one of the monorepo examples with full feature demonstrations: | Example | Description | Command | | -------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ | | `with-ai-sdk-v7` | Vercel AI SDK v7 integration | `npx assistant-ui create my-app -e with-ai-sdk-v7` | | `with-eve` | Eve agent integration | `npx assistant-ui create my-app -e with-eve` | | `with-artifacts` | HTML artifact rendering with live preview | `npx assistant-ui create my-app -e with-artifacts` | | `with-langgraph` | LangGraph agent with custom tools | `npx assistant-ui create my-app -e with-langgraph` | | `with-google-adk` | Google ADK agent integration | `npx assistant-ui create my-app -e with-google-adk` | | `with-cloud` | Assistant Cloud persistence | `npx assistant-ui create my-app -e with-cloud` | | `with-ag-ui` | [AG-UI protocol](/docs/runtimes/ag-ui/overview) integration | `npx assistant-ui create my-app -e with-ag-ui` | | `with-assistant-transport` | Custom backend via Assistant Transport | `npx assistant-ui create my-app -e with-assistant-transport` | | `with-resumable-stream` | Resumable LLM stream that survives reload mid-response | `npx assistant-ui create my-app -e with-resumable-stream` | | `with-chain-of-thought` | Chain-of-thought reasoning, tool calls, and source citations | `npx assistant-ui create my-app -e with-chain-of-thought` | | `with-external-store` | External message store | `npx assistant-ui create my-app -e with-external-store` | | `with-interactables` | AI-driven interactive UI components | `npx assistant-ui create my-app -e with-interactables` | | `with-openui` | [OpenUI](/docs/tools/openui) generative UI integration | `npx assistant-ui create my-app -e with-openui` | | `with-custom-thread-list` | Custom thread list UI | `npx assistant-ui create my-app -e with-custom-thread-list` | | `with-react-hook-form` | React Hook Form integration | `npx assistant-ui create my-app -e with-react-hook-form` | | `with-ffmpeg` | FFmpeg video processing tool | `npx assistant-ui create my-app -e with-ffmpeg` | | `with-elevenlabs-conversational` | Realtime voice with ElevenLabs | `npx assistant-ui create my-app -e with-elevenlabs-conversational` | | `with-livekit` | Realtime voice with LiveKit | `npx assistant-ui create my-app -e with-livekit` | | `with-elevenlabs-scribe` | ElevenLabs voice transcription | `npx assistant-ui create my-app -e with-elevenlabs-scribe` | | `with-expo` | Expo / React Native | `npx assistant-ui create my-app -e with-expo` | | `with-react-ink` | Terminal UI chat | `npx assistant-ui create my-app -e with-react-ink` | | `with-react-router` | React Router v7 integration | `npx assistant-ui create my-app -e with-react-router` | | `with-tanstack` | TanStack Start integration | `npx assistant-ui create my-app -e with-tanstack` | **Examples** ``` # Create with default template npx assistant-ui@latest create my-app # Create with cloud template npx assistant-ui@latest create my-app -t cloud # Create with cloud + clerk template npx assistant-ui@latest create my-app -t cloud-clerk # Create from an example npx assistant-ui@latest create my-app --example with-langgraph # Create with specific package manager npx assistant-ui@latest create my-app --use-pnpm # Skip package installation npx assistant-ui@latest create my-app --skip-install ``` **Options** ``` Usage: assistant-ui create [project-directory] [options] create a new project Arguments: project-directory name of the project directory Options: -t, --template