Guide to the assistant-ui runtime system, single-thread state, and the imperative runtime API in @assistant-ui/react. Use when creating a runtime (useLocalRuntime with a ChatModelAdapter, useExternalStoreRuntime for Redux/Zustand, useRemoteThreadListRuntime), wiring AssistantRuntimeProvider, or reading/mutating thread, message, and composer state and events. Covers the unified hooks useAui, useAuiState, useAuiEvent (composer.send, thread.runStart, thread.runEnd), legacy hooks (useAssistantRuntim
Detected risks:
The runtime skill provides comprehensive guidance for working with the assistant-ui runtime system, a hierarchical state management architecture designed for conversational AI interfaces. It addresses the challenge of managing complex chat state, including threads, messages, composer input, and real-time updates in React applications. The skill covers the modern API patterns using hooks like useAui, useAuiState, and useAuiEvent for accessing and manipulating runtime state.
This skill encompasses the complete runtime hierarchy from AssistantRuntime at the top level down through ThreadListRuntime for thread management, ThreadRuntime for current conversation state, and MessageRuntime for individual message handling. It provides patterns for common operations like appending messages, canceling generation, editing content, and reloading responses. The skill also covers advanced features including event handling, capability checking, and efficient state selection to prevent unnecessary re-renders.
The primary use cases include building custom chat interfaces, implementing message management systems, handling real-time AI responses, and creating conversational UIs with React. It's targeted at frontend developers working with assistant-ui, particularly those building AI chat applications that require fine-grained control over conversation state, message lifecycle, and user interactions. The skill is essential for anyone integrating the assistant-ui library into React applications.
Use useAuiState with selectors: `const messages = useAuiState(s => s.thread.messages)` and `const isRunning = useAuiState(s => s.thread.isRunning)`. This provides reactive access to thread state with optimal re-render performance.
useAui returns the API object for performing actions like thread.append() or message.edit(), while useAuiState is used to subscribe to state changes reactively. Use useAui for operations and useAuiState for reading state.
Get the message API using `api.thread().message(index)`, then call methods like `message.edit()` or `message.reload()`. The index refers to the message position in the thread's message array.
All runtime hooks must be called inside an AssistantRuntimeProvider component. If you get 'Cannot read property of undefined' errors, verify that your components are wrapped with the provider.
Use the useAuiEvent hook with event names like 'composer.send', 'thread.runStart', or 'thread.runEnd'. Example: `useAuiEvent('composer.send', (e) => { console.log('Sent in thread:', e.threadId); })`
Quick Setup:
.claude/skills/Repository
assistant-ui/skills