setup

SKILL.md

assistant-ui Setup

Always consult assistant-ui.com/llms.txt for the latest API.

The assistant-ui CLI scaffolds projects, adds components, and keeps an install current. This skill covers the CLI end to end and the decision of which runtime adapter to wire up next; installing the styled UI itself is elements.

References

./references/ai-sdk.md -- @assistant-ui/ai-sdk (v7): transport, frontend tools, multi-step, approval, quote context, token usage, history, useAISDKRuntime

./references/ai-sdk-legacy.md -- pinned @assistant-ui/react-ai-sdk (v6, v5) and @assistant-ui/react-data-stream (v4) setups

./references/langgraph.md -- @assistant-ui/react-langgraph: streaming, interrupts, message editing, threads, agent state

./references/langchain.md -- @assistant-ui/react-langchain: the useStream-based LangGraph adapter, and its comparison to react-langgraph

./references/google-adk.md -- @assistant-ui/react-google-adk: streaming, tool confirmations, auth flows, input requests, artifacts

./references/a2a.md -- @assistant-ui/react-a2a: A2AClient, task states, artifacts, multi-tenancy

./references/ag-ui.md -- @assistant-ui/react-ag-ui: agent state, interrupts, subagent nesting, custom events

./references/eve.md -- @assistant-ui/eve: sessions, connector authorization, withEve + withAui

./references/opencode.md -- @assistant-ui/react-opencode: permissions, questions, sub-agent tasks, session extras

./references/claude-managed-agents.md -- wiring Anthropic Managed Agents sessions through useExternalStoreRuntime

./references/custom-backend.md -- useLocalRuntime and useExternalStoreRuntime for a backend with no dedicated adapter

./references/tanstack.md -- Vite + TanStack Router/Start setup

./references/mastra.md -- Mastra full-stack and separate-server patterns over the AI SDK runtime

./references/cloudflare-agents.md -- Durable Object agents via @cloudflare/ai-chat and useAISDKRuntime

./references/providers.md -- LLM gateways, a ChatGPT/Codex subscription for local dev, and Electron

./references/devtools.md -- @assistant-ui/react-devtools, DevToolsModal, custom plugins

CLI decision flow

New app / empty directory: npx assistant-ui@latest create <name>

Existing project with a package.json: npx assistant-ui@latest init

Add one or more styled components to a project that already has a runtime: npx assistant-ui@latest add <items...> (see elements)

Bump @assistant-ui/* versions: npx assistant-ui@latest update

Migrate across a breaking release: npx assistant-ui@latest upgrade (see update for the full migration map)

Connect an editor to the docs: npx assistant-ui@latest mcp

Collect environment info for a bug report: npx assistant-ui@latest info

Diagnose version drift or a broken install: npx assistant-ui@latest doctor

Open Claude Code with these skills preloaded: npx assistant-ui@latest agent "add a chat sidebar"

create

npx assistant-ui@latest create my-app
npx assistant-ui@latest create my-app -t cloud-clerk
npx assistant-ui@latest create my-app -e with-langgraph
npx assistant-ui@latest create my-app --native   # Expo, equivalent to -e with-expo
npx assistant-ui@latest create my-app --ink      # React Ink, equivalent to -e with-react-ink

Templates (-t, --template):

Template
Contents

default
Vercel AI SDK, useChatRuntime

minimal
Bare-bones starting point with local components

cloud
AssistantCloud-backed persistence

cloud-clerk
AssistantCloud persistence with Clerk auth

langchain
LangGraph starter on the @assistant-ui/react-langchain adapter

mcp
MCP tools plus the MCP Apps renderer

eve
Eve agent on eve/next

There is no langgraph template; the LangGraph-backed starter is langchain (react-langchain), and -e with-langgraph scaffolds the raw @assistant-ui/react-langgraph adapter instead.

Examples (-e, --example), each a full feature demo:

Example
Demonstrates

with-ai-sdk-v7
Vercel AI SDK v7

with-eve
Eve agent integration

with-artifacts
HTML artifact rendering with live preview

with-langgraph
LangGraph agent with custom tools

with-google-adk
Google ADK agent

with-ag-ui
AG-UI protocol

with-cloud
AssistantCloud persistence

with-assistant-transport
Custom backend via Assistant Transport

with-resumable-stream
Resumable stream that survives a reload mid-response

with-chain-of-thought
Reasoning, tool calls, source citations

with-external-store
External message store

with-interactables
AI-driven interactive UI components

with-openui
OpenUI generative UI

with-custom-thread-list
Custom thread list UI

with-react-hook-form
React Hook Form integration

with-ffmpeg
FFmpeg video processing tool

with-elevenlabs-conversational
Realtime voice, ElevenLabs

with-livekit
Realtime voice, LiveKit

with-elevenlabs-scribe
Voice transcription, ElevenLabs

with-expo
Expo / React Native (also --native)

with-react-ink
Terminal UI chat (also --ink)

with-react-router
React Router v7

with-tanstack
TanStack Start

Other flags: -p, --preset <name-or-url> applies a playground preset (e.g. chatgpt) via shadcn add after scaffolding, and may combine with --template but not with --example, --native, or --ink; --use-npm / --use-pnpm / --use-yarn / --use-bun pin the package manager; --skip-install skips installing packages; --skills / --no-skills add or skip this repository's agent skills (prompted when omitted in a TTY). In a non-interactive shell, an omitted -t/-e defaults to the default template, and an omitted project directory defaults to my-aui-app.

init

npx assistant-ui@latest init

For an existing project with a package.json: detects the project, runs shadcn add for the quick-start component, adds the default components, and configures TypeScript paths. Flags: -y, --yes skips the confirmation prompt (use it in CI or an agent shell), -o, --overwrite replaces existing files, -c, --cwd <dir> picks the project, --use-npm / --use-pnpm / --use-yarn / --use-bun pin the package manager, and --skip-install skips installing packages. Run without a package.json and it forwards to create instead.

add

npx assistant-ui@latest add thread thread-list

Once a runtime is wired up, add fetches styled components from the assistant-ui registry (r.assistant-ui.com), installing their npm dependencies and TypeScript types and resolving registry dependencies (thread also pulls markdown-text, tool-fallback, reasoning, and more). -y, --yes skips the confirmation prompt (default true), -o, --overwrite replaces existing files, and -p, --path retargets the install directory. See elements for the full catalog, the runtime-connected (.aui) versus standalone split, and the Radix/Base UI style-aware registry URL.

Keeping an install current

Command
Purpose

assistant-ui update [--dry]
Bump every installed @assistant-ui/* package to latest; --dry prints the command instead of running it

assistant-ui upgrade [-d] [-p] [--verbose]
Run every bundled codemod for the current major in order; -d dry-runs, -p prints transformed files

assistant-ui codemod <name> <source> [-d] [-p]
Run one named codemod instead of the full upgrade sequence

assistant-ui mcp [--cursor|--windsurf|--vscode|--zed|--claude-code|--claude-desktop]
Register the hosted MCP docs endpoint (https://www.assistant-ui.com/mcp) for the named IDE, or the local @assistant-ui/mcp-docs-server stdio server for Zed and Claude Desktop, which only launch local servers

assistant-ui info
Print CLI, OS, package manager, framework, installed @assistant-ui/*/ecosystem versions, as a paste-ready block for a bug report

assistant-ui doctor [--no-network]
Diagnose an existing install (version drift across @assistant-ui/* packages, misconfiguration); --no-network skips the npm registry check for latest versions

assistant-ui agent "<prompt>" [--dry]
Launch Claude Code preloaded with the assistant-ui skills and the given prompt; --dry prints the command instead of running it

Never run codemod v0-8/ui-package-split against a current (0.15.x) install; its @assistant-ui/react-ui destination predates the current runtime and upgrade already excludes it. For the full version table, migration order, and 0.15.x follow-up moves (registry paths, AuiConfig, threads.selectionChanged), see update.

Pick a runtime

By framework, when one already fits:

Backend
Hook
Package
Reference

Vercel AI SDK v7
useChatRuntime
@assistant-ui/ai-sdk
ai-sdk.md

LangGraph Cloud (raw SDK)
useLangGraphRuntime
@assistant-ui/react-langgraph
langgraph.md

LangGraph Cloud (useStream)
useStreamRuntime
@assistant-ui/react-langchain
langchain.md

Google ADK (JS or Python)
useAdkRuntime
@assistant-ui/react-google-adk
google-adk.md

A2A v1.0 agent server
useA2ARuntime
@assistant-ui/react-a2a
a2a.md

AG-UI agent server
useAgUiRuntime
@assistant-ui/react-ag-ui
ag-ui.md

Eve (eve/next)
useEveAgentRuntime
@assistant-ui/eve
eve.md

OpenCode server (experimental)
useOpenCodeRuntime
@assistant-ui/react-opencode
opencode.md

Claude Managed Agents session
useExternalStoreRuntime + useRemoteThreadListRuntime
@assistant-ui/react (no dedicated adapter)
claude-managed-agents.md

By need, when no framework adapter fits (full decision tree in custom-backend.md):

You need
Hook
Reference

A fetch call to your API; the runtime owns state
useLocalRuntime
custom-backend.md

Messages already live in redux, zustand, tanstack-query
useExternalStoreRuntime
custom-backend.md

Backend already emits the data stream protocol
useDataStreamRuntime
../streaming/SKILL.md

Backend streams full agent-state snapshots, or needs bidirectional commands
useAssistantTransportRuntime
../streaming/SKILL.md

Framework and provider wiring guides, all layered on the AI SDK runtime above rather than a dedicated adapter: mastra.md (full-stack or separate server), cloudflare-agents.md (Durable Object agents), and providers.md (LLM gateways for routing and BYOK, a ChatGPT/Codex subscription for local dev without an API key, and Electron's hosted-backend versus local-main-process split).

Platform targets

Target
Package
Scaffold
Skill

Web (React)
@assistant-ui/react
create
this skill, elements

Expo / React Native
@assistant-ui/react-native + @assistant-ui/metro
create <name> --native (or -e with-expo)
react-native

Terminal
@assistant-ui/react-ink + @assistant-ui/react-ink-markdown
create <name> --ink (or -e with-react-ink)
ink

Vite-based web apps (TanStack Start, plain Vite, Nuxt) are not a create template; see tanstack.md for manual setup and the aui() compiler plugin from @assistant-ui/vite.

Common Gotchas

npx assistant-ui create picks the default template with no prompt

Stdin is not a TTY (CI, an agent shell). Pass -t/-e explicitly instead of relying on the interactive picker.

"Only one scaffold selector can be provided"

--template, --example, --native, and --ink are mutually exclusive. --preset may pair with --template but not with the other three.

init hangs in CI or an agent shell

Pass -y, --yes so it skips its confirmation prompt; add -o, --overwrite when it should replace files a previous run left behind.

A dependency on @assistant-ui/styles or @assistant-ui/react-ui fails to resolve or install

Both packages are retired (@assistant-ui/styles is marked deprecated on npm). Styling now comes from the elements the CLI copies into your project; remove the dependency and run npx assistant-ui@latest add thread.

Cannot find module '@/components/assistant-ui/thread'

Components moved under elements/ with a .aui suffix on runtime-connected files: @/components/assistant-ui/elements/thread.aui. See elements.

add reinstalls a component you already customized

Pass -o, --overwrite deliberately, or move your edits aside first; a plain add skips a file that already exists.

Registry install fails mid-create

create still finishes the project; rerun the printed retry command from the project directory once the registry or network issue clears.

Related Skills

elements -- install and customize the styled Thread, ThreadList, and 120+ catalog components via add

primitives -- unstyled building blocks when composing your own UI instead of elements

runtime -- the chosen runtime's hooks, adapters, events, and capabilities in depth

update -- version detection, the full migration map, and the codemod list behind upgrade

react-native -- Expo / React Native specifics once scaffolded with --native

ink -- React Ink terminal specifics once scaffolded with --ink

cloud -- AssistantCloud persistence behind the cloud and cloud-clerk templates

tools -- defining tools once a runtime is wired up