./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

setup

assistant-ui Setup

References