OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add assistant-ui/skills --skill runtime
Guide to the assistant-ui runtime system, the state and action layer behind every chat surface, in @assistant-ui/react. Use when creating a runtime (useLocalRuntime with a ChatModelAdapter, useExternalStoreRuntime for Redux or Zustand backed stores, useRemoteThreadListRuntime, useCloudThreadListRuntime, useAssistantTransportRuntime), wiring AssistantRuntimeProvider, or reading and mutating thread, message, composer, and attachment state. Covers useAui, useAuiState, and useAuiEvent, including the one primitive or stable reference selector rule from hooks/state.mdx, the property scope accessors (aui.thread, aui.threads, aui.message, aui.composer, aui.part, aui.threadListItem) with source availability, the AuiConfig plus AuiProvider grammar (config, extends, isolated roots, and the config prop on AssistantRuntimeProvider), the s.optional.<scope> view, the threads.selectionChanged event and the events it replaced, RuntimeCapabilities including refetchThread, and the attachment, speech, dictation, feedback, suggestion, and history adapters. Route here for a provider error ('Cannot read property of undefined'), a removed v0.12 hook import, an infinite re-render from an object literal selector, or state not updating. For multi-thread list UI and switching between conversations use thread-list instead; for toolkit definitions and tool call UI use tools instead.
npx skills add assistant-ui/skills --skill runtime
Always consult assistant-ui.com/llms.txt for the latest API.
A runtime is the state and action layer behind a chat UI: it owns messages, threads, branching, and run lifecycle, and every primitive and hook reads from it through a uniform AssistantClient. There are two ways to build one. LocalRuntime (useLocalRuntime) owns the message store for you; you implement one ChatModelAdapter.run function and branching, editing, and regeneration come for free. ExternalStoreRuntime (useExternalStoreRuntime) is the inverse: you own the messages, and UI features turn on based on which callbacks you supply. Framework adapters such as useChatRuntime (@assistant-ui/ai-sdk) and protocol runtimes such as useAssistantTransportRuntime are built on one of these two. Once mounted under AssistantRuntimeProvider, every runtime is read and driven the same way, through useAui, useAuiState, and useAuiEvent.
modelContext and tools resolve independently of the thread scope; see runtime-concepts.md and the tools skill. Every node in the tree is reachable from aui.<scope> (imperative) or s.<scope> inside a useAuiState selector (reactive), scoped automatically to where the calling component is rendered.
useAui() returns the current AssistantClient. It does not subscribe to state, so its identity only changes on a structural change (for example switching threads); use it in event handlers and imperative code.
useAuiState(selector) subscribes to a slice of AssistantState and re-renders only when the selected value changes (compared with Object.is). The selector runs on every store update, so it must return a primitive or a stable reference, never a fresh object or array literal, and never the whole state (that throws).
Call useAuiState once per value (or compose several calls); do not spread a scope into a new object to bundle values together.
useAuiEvent(nameOrSelector, callback) subscribes for the component's lifetime. The callback runs inside an effect-event shim, so the latest closure fires without a memoized reference.
As of 0.15, aui.<scope> is a property, not a call; calling it (aui.thread()) still works but is deprecated. Methods on a scope keep their parentheses.
Selecting an unavailable scope no longer throws; aui.message is always truthy. Check availability before use with source, which is null when the scope is not mounted:
source, query, and name are reserved accessor properties and never resolve to scope methods.
AuiProvider mounts an AssistantClient for a subtree. Its config prop must be built with AuiConfig({...}), imported from @assistant-ui/react (raw object literals are a type error). At the top level config alone creates the subtree's client. Nested under a parent provider, extends is mandatory: extends={aui} extends the parent client, extends={null} isolates a fresh root (dev enforced). AssistantRuntimeProvider installs an AuiProvider internally and additionally accepts config to attach extra scopes (such as a toolkit) alongside the runtime's own scopes; use it instead of wiring AuiProvider by hand around a runtime.
A config is plain data: hoist it to module scope, build it inline per render, or memoize it, the provider never relies on config identity. ref on AuiProvider receives the resulting client after mount.
Most events are deprecated in favor of deriving the same transition from useAuiState, which is correct on first render and replay in a way an event handler is not.
| Event | Status |
|---|---|
threads.selectionChanged | Current: fires once per main-thread switch with { threadId, previousThreadId }. Does not fire for the initially selected thread on mount |
thread.modelContextUpdate | Current: the model context lives in a provider, not in state, so there is no state-derivable equivalent |
composer.attachmentAddError | Current: reason is "no-adapter" | "not-accepted" | "adapter-error" |
composer.send, composer.attachmentAdd | Deprecated: observe composer text / attachments |
thread.runStart, thread.runEnd | Deprecated: observe s.thread.isRunning flipping |
thread.initialize | Deprecated: observe s.thread.messages becoming non-empty |
threadListItem.switchedTo, threadListItem.switchedAway | Deprecated: use threads.selectionChanged, filtering by id inside a per-item scope if needed |
The deprecated pair still fires and keeps working until the next major. threads.selectionChanged also fires in situations the old pair did not, such as switchToNewThread() and a deep-linked initial thread resolving after mount.
s.optional.<scope> resolves to undefined instead of throwing when a scope is not mounted, the safe way to read a scope from a component that renders both inside and outside it.
The imperative equivalent is aui.<scope>.source != null.
RuntimeCapabilities (from @assistant-ui/core): switchToBranch, switchBranchDuringRun, edit, reload, delete, cancel, refetchThread, unstable_copy, speech, dictation, voice, attachments, feedback, queue. Runtimes derive nearly all of these from what you supply (a callback, an adapter) rather than an explicit option; unstable_copy is the one flag ExternalStoreRuntime lets you force off via unstable_capabilities. refetchThread reports whether aui.threads.reloadMainThread() will refresh the open thread in place or fall back to remounting the runtime; see runtime-concepts.md.
"Cannot read property of undefined"
AssistantRuntimeProvider (or an AuiProvider whose config supplies the scope).s.optional.<scope> or guard on aui.<scope>.source != null.Infinite re-renders from useAuiState
A legacy hook import fails to resolve
useAssistantRuntime, useThreadRuntime, useThread, useMessage, useComposer, useMessagePart, useAttachment, useThreadListItem and friends were removed in 0.15. See state-hooks.md for the full mapping, or the update skill.State not updating
useAuiState rather than reading getState() in render; getState() is a one-time snapshot, not a subscription.Multiple threads or a conversation sidebar
threads.selectionChanged consumersThread and composer components that read this state for youAssistantCloud, managed persistence, and useChatRuntime({ cloud })import { useAui } from "@assistant-ui/react";
const aui = useAui();
aui.thread.append({ role: "user", content: [{ type: "text", text: "Hello!" }] });
aui.thread.cancelRun();import { useAuiState } from "@assistant-ui/react";
const isRunning = useAuiState((s) => s.thread.isRunning); // primitive: correct
const messages = useAuiState((s) => s.thread.messages); // stable array reference: correct
// Wrong: a new object literal every call re-renders on every store update
const bad = useAuiState((s) => ({ isRunning: s.thread.isRunning, text: s.composer.text }));import { useAuiEvent } from "@assistant-ui/react";
useAuiEvent("thread.modelContextUpdate", ({ threadId }) => {
console.log("Model context updated", threadId);
});aui.thread.getState(); // property accessor
aui.threads.switchToNewThread();
aui.thread.composer().send(); // composer() is a method of the thread scope
aui.thread.message({ index: 0 }); // selector object, not a bare indexif (aui.message.source != null) {
aui.message.reload();
}import { AssistantRuntimeProvider, AuiConfig, AuiProvider, Tools, useAui } from "@assistant-ui/react";
// Runtime root: config attaches extra scopes next to the runtime's own
const config = AuiConfig({ tools: Tools({ toolkit }) });
<AssistantRuntimeProvider runtime={runtime} config={config}>{children}</AssistantRuntimeProvider>;
// Nested scope: extend the parent client
function MessageScope({ children }: { children: React.ReactNode }) {
const aui = useAui();
const nested = AuiConfig({ tools: Tools({ toolkit: extraToolkit }) });
return <AuiProvider extends={aui} config={nested}>{children}</AuiProvider>;
}
// Isolated root: detach from any parent client
const isolated = AuiConfig({});
<AuiProvider extends={null} config={isolated}>{children}</AuiProvider>;const aui = useAui();
const thread = aui.thread;
thread.append({ role: "user", content: [{ type: "text", text: "Hello" }] });
thread.startRun({ parentId: null });
thread.cancelRun();
const state = thread.getState(); // { messages, isRunning, capabilities, composer, ... }
const message = thread.message({ index: 0 }); // or { id: messageId }
message.reload();
message.switchToBranch({ position: "next" });
message.submitFeedback({ type: "positive" });
const editComposer = message.composer();
editComposer.beginEdit();
editComposer.setText("Updated");
editComposer.send();const partType = useAuiState((s) => s.optional.part?.type);const capabilities = useAuiState((s) => s.thread.capabilities);