setup

assistant-ui Setup

Always consult [assistant-ui.com/llms.txt](https://www.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):

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:

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

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:

By need, when no framework adapter fits (full decision tree in custom-backend.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

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