SuperAPI AI Directory

setup

Coding & development

View repository

Updated 10-16 14:11

About this skill

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

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