| name | setup |
| description | Installs and configures assistant-ui in a project via the CLI, and picks the right runtime for a backend. Use for first-time install, scaffold, or config: `npx assistant-ui@latest create my-app` (templates default, minimal, cloud, cloud-clerk, langchain, mcp, eve), `npx assistant-ui@latest init [--yes] [--overwrite]` in an existing Next.js app, or `npx assistant-ui@latest add` registry components (thread, markdown-text, thread-list, tool-fallback). Also covers the other CLI verbs: doctor, info, update, upgrade, mcp, and agent. Use to choose a runtime hook for a backend: useChatRuntime (AI SDK v7), useLangGraphRuntime, useAgUiRuntime, useA2ARuntime, useLocalRuntime (custom streaming API), or useExternalStoreRuntime (Redux/Zustand). Covers Vite/TanStack Start setup, Expo (--native) and React Ink (--ink) scaffolds, shadcn and Base UI registry styles, the playground --preset flag, and avoiding the deprecated @assistant-ui/styles and @assistant-ui/react-ui packages. For upgrading an existing install or post-upgrade breakage use update; for building UI from raw parts use primitives. |
| license | MIT |
assistant-ui Setup
Always consult assistant-ui.com/llms.txt for the latest API.
CLI Commands
Quick Decision Flow
- Existing Next.js app (
package.json exists): use npx assistant-ui@latest init
- Existing app in CI/agent/non-interactive shell: use
npx assistant-ui@latest init --yes
- Existing app + force overwrite of conflicts: add
--overwrite
- New app / empty directory: use
npx assistant-ui@latest create <name>
- Need specific starter template: add
-t <default|minimal|cloud|cloud-clerk|langchain|mcp|eve>
- Need a curated example: use
npx assistant-ui@latest create <name> --example <example>
- Need playground preset config: use
npx assistant-ui@latest create <name> --preset <name-or-url>
- Expo / React Native app:
npx assistant-ui@latest create <name> --native
- Terminal (React Ink) app:
npx assistant-ui@latest create <name> --ink
New Project (create)
npx assistant-ui@latest create my-app -t minimal
npx assistant-ui@latest create my-app -t cloud-clerk
npx assistant-ui@latest create my-app --preset chatgpt
Templates:
| Template | Description |
|---|
default | Default template with Vercel AI SDK |
minimal | Bare-bones starting point |
cloud | Cloud-backed persistence starter |
cloud-clerk | Cloud-backed starter with Clerk auth |
langchain | LangGraph starter using the @assistant-ui/react-langchain adapter |
mcp | MCP tools + MCP Apps renderer starter |
eve | Eve agent + Next.js starter |
There is no langgraph template; that path is now the langchain template (or the with-langgraph example for the @assistant-ui/react-langgraph adapter directly).
Examples (--example <name>) currently include: with-ag-ui, with-ai-sdk-v7, with-artifacts, with-assistant-transport, with-chain-of-thought, with-cloud, with-custom-thread-list, with-elevenlabs-conversational, with-elevenlabs-scribe, with-eve, with-expo, with-external-store, with-ffmpeg, with-google-adk, with-interactables, with-langgraph, with-livekit, with-react-hook-form, with-react-ink, with-react-router, with-resumable-stream, with-tanstack.
Other create flags: --use-npm / --use-pnpm / --use-yarn / --use-bun, --skip-install, and --skills / --no-skills (installs the assistant-ui agent skills for AI coding assistants; defaults to on in a non-TTY shell).
When -t is omitted:
- Interactive shell (TTY): an interactive template picker is shown.
- Non-interactive shell (CI/agent): template defaults to
default.
If no project directory is provided in a non-interactive shell, create uses my-aui-app.
Existing Next.js Project (init)
npx assistant-ui@latest init --yes
The init command is for existing projects only (requires package.json).
If no project is found, it automatically forwards to create.
Passing --preset to init also forwards to create (compatibility path).
The --yes flag runs non-interactively (no prompts).
Add Registry Components
npx assistant-ui@latest add thread
npx assistant-ui@latest add markdown-text
npx assistant-ui@latest add thread-list
Registry: https://r.assistant-ui.com/{name}.json
See references/registry-components.md for the full item list.
Other CLI Commands
| Command | Purpose |
|---|
assistant-ui doctor | Diagnose an existing install (version drift, misconfiguration); --no-network skips the registry check |
assistant-ui info | Print environment and package information for bug reports |
assistant-ui update | Bump assistant-ui packages to their latest versions (--dry prints the command) |
assistant-ui upgrade | Run the version codemods (-d dry run, -p print transformed files) |
assistant-ui mcp | Install the MCP docs server for Cursor, Windsurf, VSCode, Zed, Claude Code, or Claude Desktop |
assistant-ui agent "<prompt>" | Launch Claude Code preloaded with the assistant-ui skills (--dry prints the command) |
Template Code Policy
When using CLI templates (npx assistant-ui@latest create), never modify generated code unless explicitly requested.
Non-Default Setups
For runtimes other than AI SDK or frameworks other than Next.js, consult the reference files:
Runtime adapters with no reference file here (consult the docs site): @assistant-ui/react-opencode (useOpenCodeRuntime), @assistant-ui/react-pi, and @assistant-ui/eve (the eve template).
Platform targets
| Target | Package | Scaffold |
|---|
| Web (React) | @assistant-ui/react | create |
| Expo / React Native | @assistant-ui/react-native + @assistant-ui/metro | create <name> --native |
| Terminal | @assistant-ui/react-ink + @assistant-ui/react-ink-markdown | create <name> --ink |
Deprecated Packages
NEVER install @assistant-ui/styles or @assistant-ui/react-ui; both are deprecated and deleted.
Troubleshooting
For issues not covered by the reference files, use the docs website:
- Fetch the index:
https://www.assistant-ui.com/llms.txt (compact table of contents)
- Fetch specific pages: Append
.mdx to the docs URL, e.g. https://www.assistant-ui.com/docs/runtimes/ai-sdk.mdx
