runtime — Claude Code skill: connecting stores to chat interfaces
Learn how assistant-ui runtimes connect chat interfaces to state and actions. Useful when wiring a provider or tracking down repeated renders.
MIT 6,500 installs ★ 29 updated 2026-10-13
npx skills add assistant-ui/skills --skill runtime -a claude-codeWhat runtime does
A runtime connects a chat UI to its messages, threads, and run lifecycle. This skill covers two approaches: useLocalRuntime manages message storage and takes a ChatModelAdapter, while useExternalStoreRuntime lets an app supply its own store, such as Redux or Zustand, along with the needed handlers.
It also explains AssistantRuntimeProvider, the useAui, useAuiState, and useAuiEvent hooks, and access to thread, message, and composer state. A useAuiState selector should return a primitive or stable reference. Returning a fresh object on each call triggers renders on store updates. Nested AuiProvider instances need an extends value, and their configuration is built with AuiConfig from @assistant-ui/react.
Use the guide when chat state stops updating or a provider error appears. It also covers removed hook imports and adapters for attachments, speech, dictation, feedback, suggestions, and history.
What it helps with
- connect Redux or Zustand to a chat interface
- configure a runtime and
AssistantRuntimeProvider - read thread, message, or composer state
- trace renders caused by an unstable selector
- fix an outdated hook import
Example prompts for the agent
- Show me how to connect
useLocalRuntimewithChatModelAdapterin this project. - Find why this
useAuiStateselector triggers repeated renders. - Explain how to configure a nested
AuiProviderwithAuiConfig.
How to install runtime
1Skills CLI (Vercel)
npx skills add assistant-ui/skills --skill runtime -a claude-code2Manually: put the files in place
~/.claude/skills/runtime/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/runtime/
1Skills CLI (Vercel)
npx skills add assistant-ui/skills --skill runtime -a codex2Manually: put the files in place
.agents/skills/runtime/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add assistant-ui/skills --skill runtime -a cursor2Manually: put the files in place
.cursor/skills/runtime/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install assistant-ui/skills assistant-ui/skills/runtime2Manually: put the files in place
.github/skills/runtime/SKILL.md1Skills CLI (Vercel)
npx skills add assistant-ui/skills --skill runtime -a gemini-cli2Platform CLI
gemini skills install https://github.com/assistant-ui/skills --path assistant-ui/skills/runtimeManually: put the files in place
.devin/skills/runtime/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add assistant-ui/skills --skill runtime -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about runtime
How do I install runtime in Claude Code?
Run npx skills add assistant-ui/skills --skill runtime -a claude-code. The skill file is installed at ~/.claude/skills/runtime/SKILL.md.
What does the runtime skill do?
It explains assistant-ui runtime setup, local and external message stores, and ways to read chat state with hooks.
Why does useAuiState trigger repeated renders?
The selector result is compared with Object.is. A new object or array on each call changes the result after store updates; return a primitive or stable reference instead.
Source text
SKILL.md · MIT
---
name: runtime
description: "Guide to the assistant-ui runtime system, the state and action layer behind every chat surface. 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 with the stable selector rule, the scope accessors (aui.thread, aui.message, aui.composer, and siblings), the AuiConfig plus AuiProvider grammar, RuntimeCapabilities, 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 use thread-list instead; for toolkit definitions and tool call UI use tools instead."
license: MIT
---
# assistant-ui Runtime
**Always consult [assistant-ui.com/llms.txt](https://www.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`.
## References
- [./references/local-runtime.md](./references/local-runtime.md) -- useLocalRuntime deep dive: streaming, tool calls, human-in-the-loop, approval gates, resumeRun
- [./references/external-store.md](./references/external-store.md) -- useExternalStoreRuntime deep dive: handler matrix, branching, queueing, tool results
- [./references/state-hooks.md](./references/state-hooks.md) -- useAui, useAuiState, useAuiEvent, state shape, removed legacy hooks
- [./references/types.md](./references/types.md) -- ThreadMessage, MessageStatus, MessagePart, attachment, and capability types
- [./references/adapters.md](./references/adapters.md) -- attachment, speech, dictation, feedback, suggestion, and history adapters
- [./references/voice.md](./references/voice.md) -- realtime duplex voice with RealtimeVoiceAdapter
- [./references/runtime-concepts.md](./references/runtime-concepts.md) -- unstable_ policy, useAssistantTransportRuntime, MessageNotSentError, reloadMainThread, message timing
## Runtime hierarchy
```
AssistantRuntime
├── ThreadListRuntime (threads)
│ └── ThreadListItemRuntime[] (threadListItem)
└── ThreadRuntime (thread)
├── ComposerRuntime (composer) new-message input
├── SuggestionRuntime[] (suggestion) follow-up prompts, via thread.suggestions
└── MessageRuntime[] (message)
├── ComposerRuntime (composer) edit-message input
├── MessagePartRuntime[] (part)
├── ChainOfThoughtRuntime (chainOfThought)
│ └── MessagePartRuntime[] (part)
└── AttachmentRuntime[] (attachment)
```
`modelContext` and `tools` resolve independently of the thread scope; see [runtime-concepts.md](./references/runtime-concepts.md) and the [tools](../tools/SKILL.md) 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, useAuiState, useAuiEvent
`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.
```tsx
import { useAui } from "@assistant-ui/react";
const aui = useAui();
aui.thread.append({ role: "user", content: [{ type: "text", text: "Hello!" }] });
aui.thread.cancelRun();
```
`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).
```tsx
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 }));
```
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.
```tsx
import { useAuiEvent } from "@assistant-ui/react";
useAuiEvent("thread.modelContextUpdate", ({ threadId }) => {
console.log("Model context updated", threadId);
});
```
## Scope accessors are properties
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.
```tsx
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 index
```
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:
```tsx
if (aui.message.source != null) {
aui.message.reload();
}
```
`source`, `query`, and `name` are reserved accessor properties and never resolve to scope methods.
## AuiConfig and AuiProvider
`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.
```tsx
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>;
```
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.
## Thread and message operations
```tsx
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();
```
## Events
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.
## Optional scopes
`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.
```tsx
const partType = useAuiState((s) => s.optional.part?.type);
```
The imperative equivalent is `aui.<scope>.source != null`.
## Capabilities
```tsx
const capabilities = useAuiState((s) => s.thread.capabilities);
```
`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](./references/runtime-concepts.md).
## Common Gotchas
**"Cannot read property of undefined"**
- Ensure hooks are called inside `AssistantRuntimeProvider` (or an `AuiProvider` whose config supplies the scope).
- For a scope that may not be mounted, read `s.optional.<scope>` or guard on `aui.<scope>.source != null`.
**Infinite re-renders from `useAuiState`**
- The selector returned a new object or array literal, including spreading a scope into one. Select primitives with separate calls, or return a memoized reference.
**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](./references/state-hooks.md) for the full mapping, or the [update](../update/SKILL.md) skill.
**State not updating**
- Use a selector with `useAuiState` rather than reading `getState()` in render; `getState()` is a one-time snapshot, not a subscription.
**Multiple threads or a conversation sidebar**
- This skill covers a single thread's state and the runtime hooks. For creating, switching, archiving, and rendering a list of threads, use the [thread-list](../thread-list/SKILL.md) skill instead.
## Related Skills
- [thread-list](../thread-list/SKILL.md) -- multi-thread UI, thread CRUD, `threads.selectionChanged` consumers
- [tools](../tools/SKILL.md) -- toolkit authoring, tool call UI, approval gates and human tools in depth
- [elements](../elements/SKILL.md) -- the styled `Thread` and composer components that read this state for you
- [cloud](../cloud/SKILL.md) -- `AssistantCloud`, managed persistence, and `useChatRuntime({ cloud })`
- [streaming](../streaming/SKILL.md) -- the DataStream and AssistantTransport wire protocols underneath the protocol runtimes
© assistant-ui · MIT · assistant-ui/skills