+ Start a conversation
+
+ {part.text}
, + Image: ({ part }) =>Tool: {part.toolName}
,
+ Reasoning: ({ part }) => Thinking
{part.text}
+
+
+
+
+
+
+
+ Drop files to attach
+
+
+
+
+ composer.dictation == null}>
+
+
+
+
+ composer.dictation != null}>
+
+
+
+
+ thread.isRunning}>
+
+
+
+
+ !thread.isRunning}>
+
+
+
+
+
+
+ );
+}
+```
diff --git a/.agents/skills/primitives/references/message.md b/.agents/skills/primitives/references/message.md
new file mode 100644
index 0000000..19804b6
--- /dev/null
+++ b/.agents/skills/primitives/references/message.md
@@ -0,0 +1,211 @@
+# MessagePrimitive
+
+Individual message display.
+
+## Parts
+
+| Part | Description |
+|------|-------------|
+| `.Root` | Message container |
+| `.Parts` | Message body with parts (canonical) |
+| `.Content` | Message body with parts |
+| `.If` | Conditional rendering (deprecated; prefer `AuiIf`) |
+| `.Error` | Render fallback when message has an error |
+| `.PartByIndex` | Render a single part by index |
+| `.Attachments` | Render message attachments |
+| `.AttachmentByIndex` | Render one attachment by index |
+
+## Basic Structure
+
+```tsx
+Characters: {text.length}
+Attachments: {attachments.length}
+ +{part.text}
+ ), + Image: ({ part }) => ( +
+ {part.toolName}
+ {part.result &&
+ ),
+ Reasoning: ({ part }) => (
+ {JSON.stringify(part.result, null, 2)}}
+
+
+ ),
+ Source: ({ part }) => (
+
+ {part.title}
+
+ ),
+ File: ({ part }) => (
+
+ 📄 {part.filename ?? "file"}
+
+ ),
+ }}
+/>
+```
+
+### Part Types
+
+| Type | Description | Properties |
+|------|-------------|------------|
+| `Text` | Plain text | `text` |
+| `Image` | Image attachment | `image` (URL) |
+| `ToolCall` | Tool invocation | `toolName`, `args`, `argsText`, `result?`, `isError?`, `artifact?` |
+| `Reasoning` | Chain-of-thought | `text` |
+| `Source` | Citation/reference | `url`, `title` |
+| `File` | File attachment | `filename?`, `data`, `mimeType` |
+
+## MessagePrimitive.If / AuiIf
+
+`MessagePrimitive.If` still exists but is deprecated. Prefer `AuiIf` for the most flexible state checks.
+
+```tsx
+Thinking...
+{part.text}
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
+```
diff --git a/.agents/skills/primitives/references/thread.md b/.agents/skills/primitives/references/thread.md
new file mode 100644
index 0000000..997bab9
--- /dev/null
+++ b/.agents/skills/primitives/references/thread.md
@@ -0,0 +1,222 @@
+# ThreadPrimitive
+
+Container for the entire chat thread.
+
+## Parts
+
+| Part | Description |
+|------|-------------|
+| `.Root` | Outermost container element |
+| `.Viewport` | Scrollable message area |
+| `.Messages` | Renders message list |
+| `.Empty` | Shown when no messages |
+| `.ScrollToBottom` | Button to scroll down |
+| `.Suggestions` | Quick reply suggestions |
+| `.If` | Conditional rendering (deprecated; prefer `AuiIf`) |
+
+## Basic Structure
+
+```tsx
+Role: {role}
+Status: {status}
+{message.content}
,
+
+ // Optional: Edit composer for message editing
+ EditComposer: () =>
+
+Welcome!
+Start a conversation
+
+
+
+ (
+
+ ),
+ }}
+ />
+
+ AI Assistant
+How can I help you today?
+
+
+
+
+
+
+ );
+}
+```
diff --git a/.agents/skills/runtime/SKILL.md b/.agents/skills/runtime/SKILL.md
new file mode 100644
index 0000000..efa6c28
--- /dev/null
+++ b/.agents/skills/runtime/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: runtime
+description: Guide for assistant-ui runtime system and state management. Use when working with runtimes, accessing state, or managing thread/message data.
+version: 0.0.1
+license: MIT
+---
+
+# assistant-ui Runtime
+
+**Always consult [assistant-ui.com/llms.txt](https://assistant-ui.com/llms.txt) for latest API.**
+
+## References
+
+- [./references/local-runtime.md](./references/local-runtime.md) -- useLocalRuntime deep dive
+- [./references/external-store.md](./references/external-store.md) -- useExternalStoreRuntime deep dive
+- [./references/thread-list.md](./references/thread-list.md) -- Thread list management
+- [./references/state-hooks.md](./references/state-hooks.md) -- State access hooks
+- [./references/types.md](./references/types.md) -- Type definitions
+
+## Runtime Hierarchy
+
+```
+AssistantRuntime
+├── ThreadListRuntime (thread management)
+│ ├── ThreadListItemRuntime (per-thread item)
+│ └── ...
+└── ThreadRuntime (current thread)
+ ├── ComposerRuntime (input state)
+ └── MessageRuntime[] (per-message)
+ └── MessagePartRuntime[] (per-content-part)
+```
+
+## State Access (Modern API)
+
+```tsx
+import { useAui, useAuiState, useAuiEvent } from "@assistant-ui/react";
+
+function ChatControls() {
+ const api = useAui();
+ const messages = useAuiState(s => s.thread.messages);
+ const isRunning = useAuiState(s => s.thread.isRunning);
+
+ useAuiEvent("composer.send", (e) => {
+ console.log("Sent in thread:", e.threadId);
+ });
+
+ return (
+ {messages.length} messages
+ {isRunning &&Generating...
} +
+
+ {isRunning && (
+
+ )}
+
+ );
+}
+```
+
+## Thread Operations
+
+```tsx
+const api = useAui();
+const thread = api.thread();
+
+// Append message
+thread.append({ role: "user", content: [{ type: "text", text: "Hello" }] });
+
+// Cancel generation
+thread.cancelRun();
+
+// Get current state
+const state = thread.getState(); // { messages, isRunning, ... }
+```
+
+## Message Operations
+
+```tsx
+const message = api.thread().message(0); // By index
+
+message.edit({ role: "user", content: [{ type: "text", text: "Updated" }] });
+message.reload();
+```
+
+## Events
+
+```tsx
+useAuiEvent("thread.runStart", () => {});
+useAuiEvent("thread.runEnd", () => {});
+useAuiEvent("composer.send", ({ threadId }) => {
+ console.log("Sent in thread:", threadId);
+});
+useAuiEvent("thread.modelContextUpdate", () => {});
+```
+
+## Capabilities
+
+```tsx
+const caps = useAuiState(s => s.thread.capabilities);
+// { cancel, edit, reload, copy, speak, attachments }
+```
+
+## Quick Reference
+
+```tsx
+// Get messages
+const messages = useAuiState(s => s.thread.messages);
+
+// Check running state
+const isRunning = useAuiState(s => s.thread.isRunning);
+
+// Append message
+api.thread().append({ role: "user", content: [{ type: "text", text: "Hi" }] });
+
+// Cancel generation
+api.thread().cancelRun();
+
+// Edit message
+api.thread().message(index).edit({ ... });
+
+// Reload message
+api.thread().message(index).reload();
+```
+
+## Common Gotchas
+
+**"Cannot read property of undefined"**
+- Ensure hooks are called inside `AssistantRuntimeProvider`
+
+**State not updating**
+- Use selectors with `useAuiState` to prevent unnecessary re-renders
+
+**Messages array empty**
+- Check runtime is configured
+- Verify API response format
diff --git a/.agents/skills/runtime/references/external-store.md b/.agents/skills/runtime/references/external-store.md
new file mode 100644
index 0000000..3ec3424
--- /dev/null
+++ b/.agents/skills/runtime/references/external-store.md
@@ -0,0 +1,321 @@
+# useExternalStoreRuntime
+
+Connect assistant-ui to custom message stores (Redux, Zustand, etc.).
+
+## Basic Usage
+
+```tsx
+import { useExternalStoreRuntime, AssistantRuntimeProvider } from "@assistant-ui/react";
+import { Thread } from "@/components/assistant-ui/thread";
+
+function App() {
+ // Your existing state
+ const [messages, setMessages] = useState{messages.length} messages
;
+}
+
+function RunningIndicator() {
+ // Only re-renders when isRunning changes
+ const isRunning = useAuiState((s) => s.thread.isRunning);
+ return isRunning ? Typing: {text}
;
+}
+
+function ThreadInfo() {
+ // Multiple values
+ const { messages, isRunning, capabilities } = useAuiState((s) => ({
+ messages: s.thread.messages,
+ isRunning: s.thread.isRunning,
+ capabilities: s.thread.capabilities,
+ }));
+}
+```
+
+### useAuiEvent
+
+Listen to runtime events.
+
+```tsx
+import { useAuiEvent } from "@assistant-ui/react";
+
+function Analytics() {
+ useAuiEvent("composer.send", (event) => {
+ analytics.track("message_sent", {
+ threadId: event.threadId,
+ messageId: event.messageId, // optional, may be undefined
+ });
+ });
+
+ useAuiEvent("thread.runStart", () => {
+ console.log("Generation started");
+ });
+
+ useAuiEvent("thread.runEnd", () => {
+ console.log("Generation completed");
+ });
+
+ return null;
+}
+```
+
+Available events:
+- `composer.send` - Message submitted from composer
+- `composer.attachmentAdd` - Attachment added in composer
+- `thread.runStart` - Generation started
+- `thread.runEnd` - Generation ended
+- `thread.initialize` - Thread is initialized
+- `thread.modelContextUpdate` - Thread model context updated
+- `threadListItem.switchedTo` - Active thread changed
+- `threadListItem.switchedAway` - Active thread changed away
+
+## State Shape
+
+```typescript
+interface AssistantState {
+ thread: {
+ messages: ThreadMessage[];
+ isRunning: boolean;
+ capabilities: RuntimeCapabilities;
+ composer: {
+ text: string;
+ attachments: Attachment[];
+ };
+ };
+ threads: {
+ mainThreadId: string;
+ newThreadId: string | null;
+ threadIds: readonly string[];
+ archivedThreadIds: readonly string[];
+ isLoading: boolean;
+ threadItems: readonly ThreadListItemState[];
+ main: ThreadState;
+ };
+ threadListItem: {
+ id: string;
+ remoteId?: string;
+ externalId?: string;
+ title?: string;
+ status: "archived" | "regular" | "new" | "deleted";
+ };
+}
+```
+
+## Legacy Hooks
+
+These still work but prefer the modern API:
+
+```tsx
+// Runtime access
+import {
+ useAssistantRuntime,
+ useThreadRuntime,
+ useMessageRuntime,
+ useComposerRuntime,
+} from "@assistant-ui/react";
+
+const assistantRuntime = useAssistantRuntime();
+const threadRuntime = useThreadRuntime();
+const messageRuntime = useMessageRuntime(); // Needs message context
+const composerRuntime = useComposerRuntime();
+
+// State subscriptions
+import {
+ useThread,
+ useThreadMessages,
+ useComposer,
+ useMessage,
+ useThreadList,
+} from "@assistant-ui/react";
+
+const thread = useThread(); // { messages, isRunning, ... }
+const messages = useThreadMessages(); // ThreadMessage[]
+const composer = useComposer(); // { text, attachments, ... }
+const message = useMessage(); // Current message (needs context)
+const threadList = useThreadList(); // Thread list state
+```
+
+## Context Requirements
+
+Some hooks require being inside specific contexts:
+
+```tsx
+// These work anywhere inside AssistantRuntimeProvider
+useAui()
+useAuiState()
+useAuiEvent()
+useAssistantRuntime()
+useThreadRuntime()
+useThread()
+useThreadMessages()
+useComposer()
+
+// These require message context (inside ThreadPrimitive.Messages)
+useMessageRuntime()
+useMessage()
+
+// These require message part context
+useMessagePartRuntime()
+```
+
+## Performance Tips
+
+### Use Selectors
+
+```tsx
+// Bad - re-renders on any state change
+const state = useAuiState((s) => s);
+
+// Good - only re-renders when messages change
+const messages = useAuiState((s) => s.thread.messages);
+
+// Better - only re-renders when message count changes
+const count = useAuiState((s) => s.thread.messages.length);
+```
+
+### Memoize Derived Data
+
+```tsx
+function MessageList() {
+ const messages = useAuiState((s) => s.thread.messages);
+
+ // Memoize expensive computations
+ const userMessages = useMemo(
+ () => messages.filter((m) => m.role === "user"),
+ [messages]
+ );
+
+ return {userMessages.length} user messages
;
+}
+```
+
+### Split Components
+
+```tsx
+// Bad - entire component re-renders
+function Chat() {
+ const messages = useAuiState((s) => s.thread.messages);
+ const isRunning = useAuiState((s) => s.thread.isRunning);
+ return (
+
+
+ );
+}
+
+// Good - components re-render independently
+function Chat() {
+ return (
+
+
+ );
+}
+
+function MessageList() {
+ const messages = useAuiState((s) => s.thread.messages);
+ return ...
;
+}
+
+function RunningIndicator() {
+ const isRunning = useAuiState((s) => s.thread.isRunning);
+ return isRunning ?
+
+ {threadIds.map((threadId) => (
+
+ ))}
+
+ );
+}
+```
+
+## Thread Item Operations
+
+```tsx
+function ThreadItem({ threadId }: { threadId: string }) {
+ const api = useAui();
+ const item = api.threads().item({ id: threadId });
+
+ const handleRename = async () => {
+ await item.rename("New Title");
+ };
+
+ const handleArchive = async () => {
+ await item.archive();
+ };
+
+ const handleDelete = async () => {
+ await item.delete();
+ };
+
+ return (
+
+
+
+
+
+
+ );
+}
+```
+
+## Using ThreadList Primitives
+
+```tsx
+import {
+ ThreadListPrimitive,
+ ThreadListItemPrimitive,
+} from "@assistant-ui/react";
+
+function ThreadList() {
+ return (
+
+
+
+
+
+
+
+
+
+
+
+ 📁
+
+
+ 🗑️
+
+
+
+
+ Loading weather for {args.city}...
;
+ }
+ return (
+
+ {result?.city}: {result?.temperature}°{result?.unit}
+
+ );
+ },
+});
+
+// Register inside the provider tree
+Searching for: {args.query}...
;
+ }
+ return (
+
+ {result?.results?.map((r: any) => (
+ {r.title}
+ ))}
+
+ );
+ },
+});
+```
+
+## Python Backend Example
+
+```python
+# langgraph_server.py
+from langgraph.graph import StateGraph, MessagesState
+from langchain_openai import ChatOpenAI
+
+model = ChatOpenAI(model="gpt-4o")
+
+def chat_node(state: MessagesState):
+ response = model.invoke(state["messages"])
+ return {"messages": [response]}
+
+graph = StateGraph(MessagesState)
+graph.add_node("chat", chat_node)
+graph.set_entry_point("chat")
+graph.set_finish_point("chat")
+
+app = graph.compile()
+
+# Run with: langgraph serve
+```
+
+## Thread Persistence
+
+LangGraph handles thread persistence server-side. The `threadId` you pass to the runtime maps to LangGraph's thread management.
+
+```tsx
+// Thread list with LangGraph
+function ThreadSelector() {
+ const [threads, setThreads] = useState([]);
+
+ useEffect(() => {
+ client.threads.list().then(setThreads);
+ }, []);
+
+ return (
+
+ );
+}
+```
+
+## Troubleshooting
+
+**"Stream not yielding events"**
+Ensure your stream function yields events in the correct format. Debug by logging events before yielding.
+
+**"Thread not persisting"**
+LangGraph persistence is server-side. Check that your LangGraph server is configured with a checkpointer.
+
+**"Tool calls not rendering"**
+Tool names must match between LangGraph and `makeAssistantToolUI`.
diff --git a/.agents/skills/setup/references/styling.md b/.agents/skills/setup/references/styling.md
new file mode 100644
index 0000000..e574e4d
--- /dev/null
+++ b/.agents/skills/setup/references/styling.md
@@ -0,0 +1,91 @@
+# Styling and Customization (shadcn Pattern)
+
+assistant-ui UI components added by `init`/`create`/`add` are local source files. Style and customize them the same way you customize shadcn components: edit local TSX and theme tokens directly.
+
+## Where to Customize
+
+- `components/assistant-ui/*`: assistant-ui registry components (thread, tool-fallback, markdown-text, etc.)
+- `components/ui/*`: shadcn base primitives (button, tooltip, dialog, sidebar, ...)
+- `app/globals.css`: theme tokens (`:root`, `.dark`) and global overrides
+- `lib/utils.ts`: `cn()` class merging helper used across components
+
+## Theme Tokens (Tailwind v4 + shadcn style)
+
+Components use shadcn theme tokens defined in `app/globals.css` and mapped to Tailwind v4 `@theme` variables. These help maintain a consistent style system.
+
+```css
+:root {
+ --background: oklch(1 0 0);
+ --foreground: oklch(0.141 0.005 285.823);
+ --primary: oklch(0.21 0.006 285.885);
+ --radius: 0.625rem;
+ /* ...other theme tokens */
+}
+
+.dark {
+ --background: oklch(0.141 0.005 285.823);
+ --foreground: oklch(0.985 0 0);
+ --primary: oklch(0.9 0.001 286.0);
+ /* ...other theme tokens */
+}
+```
+
+## Dark Mode
+
+Dark mode is class-based: toggling the `dark` class on `` switches shadcn theme tokens to dark mode values.
+
+```tsx
+// app/layout.tsx
+import { ThemeProvider } from "next-themes";
+
+
+
+
+// Floating modal chat
+
+
+```
+
+## Component-Level Customization with `cn()`
+
+Use `cn()` when customizing local component styles (including child elements like a `Button` inside `Thread`) so you can layer conditional or external classes without breaking defaults. Keep edits in registry components (`components/assistant-ui/`) and rely on shadcn primitives for consistent composition.
+
+`cn()` keeps base styles, then resolves conflicts so later classes win.
+
+```tsx
+
+```
+
+```tsx
+
+
+
+
+
+
+
+ {/* Archived section */}
+
+
+
+
+ Archived
+
+ {archived ? (
+
+ ↩️
+
+ ) : (
+
+ 📁
+
+ )}
+
+ 🗑️
+
+
+
+ {/* Header */}
+
+ );
+}
+
+function ThreadItem({
+ id,
+ isActive = false,
+ archived = false,
+}: {
+ id: string;
+ isActive?: boolean;
+ archived?: boolean;
+}) {
+ const api = useAui();
+ const item = api.threads().item({ id });
+ const state = item.getState();
+ const [isEditing, setIsEditing] = useState(false);
+ const [title, setTitle] = useState(state.title || "");
+
+ const handleRename = async () => {
+ await item.rename(title);
+ setIsEditing(false);
+ };
+
+ return (
+
+
+
+
+ {/* Thread list */}
+
+
+ {/* Archived */}
+ {archivedThreads.length > 0 && (
+
+
+ )}
+ Archived
+ {archivedThreads.map((threadId) => ( + item.switchTo()}
+ >
+ {isEditing ? (
+ setTitle(e.target.value)}
+ onBlur={handleRename}
+ onKeyDown={(e) => e.key === "Enter" && handleRename()}
+ className="flex-1 px-2 py-1 text-sm border rounded"
+ autoFocus
+ onClick={(e) => e.stopPropagation()}
+ />
+ ) : (
+ <>
+
+ {state.title || "Untitled"}
+
+
+ );
+}
+```
+
+## With Search
+
+```tsx
+function SearchableThreadList() {
+ const [search, setSearch] = useState("");
+ const api = useAui();
+ const { threads, mainThreadId } = useAuiState((s) => ({
+ threads: s.threads.threadIds,
+ mainThreadId: s.threads.mainThreadId,
+ }));
+
+ const filteredThreads = threads.filter((id) => {
+ if (!search) return true;
+ const item = api.threads().item({ id }).getState();
+ return item.title?.toLowerCase().includes(search.toLowerCase());
+ });
+
+ return (
+
+
+ {archived ? (
+
+ ) : (
+
+ )}
+
+
+
+ )}
+
+ {/* Search */}
+
+ );
+}
+```
+
+## With Drag and Drop
+
+```tsx
+import { DragDropContext, Droppable, Draggable } from "@hello-pangea/dnd";
+
+function DraggableThreadList() {
+ const api = useAui();
+ const { threads } = useAuiState((s) => ({ threads: s.threads.threadIds }));
+ const [orderedThreads, setOrderedThreads] = useState(threads);
+
+ useEffect(() => {
+ setOrderedThreads(threads);
+ }, [threads]);
+
+ const handleDragEnd = (result: any) => {
+ if (!result.destination) return;
+
+ const items = Array.from(orderedThreads);
+ const [reordered] = items.splice(result.source.index, 1);
+ items.splice(result.destination.index, 0, reordered);
+
+ setOrderedThreads(items);
+ // Optionally persist order to backend
+ };
+
+ return (
+
+ setSearch(e.target.value)}
+ placeholder="Search conversations..."
+ className="w-full px-3 py-2 border rounded-lg"
+ />
+
+
+ {/* New button */}
+
+
+ {/* Results */}
+
+ {filteredThreads.length === 0 ? (
+
+ No results
+ ) : ( + filteredThreads.map((id) => ( +
+ {orderedThreads.map((id, index) => (
+
+ {(provided) => (
+
+ ))}
+ {provided.placeholder}
+
+ )}
+
+
+ )}
+
+
+
+ {open && (
+
+ );
+}
+```
+
+## With Categories/Folders
+
+```tsx
+function CategorizedThreadList() {
+ const api = useAui();
+ const { threads } = useAuiState((s) => ({ threads: s.threads.threadIds }));
+
+ // Group by title first letter
+ const grouped = threads.reduce((acc, id) => {
+ const item = api.threads().item({ id }).getState();
+ const category = (item.title || "Untitled").charAt(0).toUpperCase();
+ if (!acc[category]) acc[category] = [];
+ acc[category].push(id);
+ return acc;
+ }, {} as Record
+
+
+ )}
+
+ {threads.map((id) => {
+ const item = api.threads().item({ id }).getState();
+ return (
+
+ );
+ })}
+
+
+ {Object.entries(grouped).map(([category, ids]) => (
+
+ );
+}
+```
diff --git a/.agents/skills/thread-list/references/management.md b/.agents/skills/thread-list/references/management.md
new file mode 100644
index 0000000..fec79a6
--- /dev/null
+++ b/.agents/skills/thread-list/references/management.md
@@ -0,0 +1,285 @@
+# Thread List Management
+
+CRUD operations for managing multiple chat threads.
+
+## Overview
+
+Thread list management allows users to:
+- Create new conversations
+- Switch between threads
+- Rename, archive, and delete threads
+- View thread history
+
+## Accessing Thread List API
+
+```tsx
+import { useAui, useAuiState } from "@assistant-ui/react";
+
+function ThreadManager() {
+ const api = useAui();
+
+ // Get thread list API
+ const threads = api.threads();
+
+ // Get current state
+ const { threadIds, mainThreadId } = useAuiState(
+ (s) => ({
+ threadIds: s.threads.threadIds,
+ mainThreadId: s.threads.mainThreadId,
+ })
+ );
+}
+```
+
+## Thread Operations
+
+### Create New Thread
+
+```tsx
+const api = useAui();
+
+// Switch to a new empty thread
+await api.threads().switchToNewThread();
+
+// Thread is created when first message is sent
+```
+
+### Switch Thread
+
+```tsx
+// By thread ID
+await api.threads().switchToThread(threadId);
+
+// Using item
+const item = api.threads().item({ id: threadId });
+await item.switchTo();
+```
+
+### Rename Thread
+
+```tsx
+const item = api.threads().item({ id: threadId });
+await item.rename("New Chat Title");
+```
+
+### Archive Thread
+
+```tsx
+const item = api.threads().item({ id: threadId });
+await item.archive();
+
+// Archived threads move to archivedThreads list
+```
+
+### Unarchive Thread
+
+```tsx
+const item = api.threads().item({ id: threadId });
+await item.unarchive();
+
+// Moves back to regular threads list
+```
+
+### Delete Thread
+
+```tsx
+const item = api.threads().item({ id: threadId });
+await item.delete();
+
+// Permanently removes thread
+// If deleting current thread, switches to another
+```
+
+### Generate Title
+
+```tsx
+const item = api.threads().item({ id: threadId });
+await item.generateTitle();
+
+// Uses AI to generate title from conversation
+```
+
+## Thread List State
+
+```typescript
+interface ThreadListState {
+ mainThreadId: string; // Current thread
+ newThreadId: string | null; // Pending new thread
+ threadIds: readonly string[]; // Regular thread IDs
+ archivedThreadIds: readonly string[];
+ isLoading: boolean;
+ threadItems: readonly ThreadListItemState[];
+}
+
+interface ThreadListItemState {
+ id: string;
+ title?: string;
+ remoteId?: string;
+ externalId?: string;
+ status: "archived" | "regular" | "new" | "deleted";
+}
+```
+
+## Subscribing to Changes
+
+```tsx
+import { useAuiState, useAuiEvent } from "@assistant-ui/react";
+
+function ThreadWatcher() {
+ // Reactive state
+ const threads = useAuiState((s) => s.threads.threadIds);
+
+ // Events
+ useAuiEvent("thread.initialize", () => {
+ console.log("New thread created");
+ });
+
+ return
+
+ ))}
+ + {category} +
+ {ids.map((id) => ( +{threads.length} threads
;
+}
+```
+
+## Item Access Patterns
+
+```tsx
+const api = useAui();
+const threads = api.threads();
+
+// By ID
+const item1 = threads.item({ id: "thread-123" });
+
+// By index (regular threads)
+const item2 = threads.item({ index: 0 });
+
+// By index (archived)
+const item3 = threads.item({ index: 0, archived: true });
+
+// Current thread
+const mainItem = threads.item("main");
+```
+
+## Batch Operations
+
+```tsx
+async function archiveThreadsByTitlePrefix(prefix: string) {
+ const api = useAui();
+ const { threadIds } = api.threads().getState();
+
+ for (const threadId of threadIds) {
+ const item = api.threads().item({ id: threadId });
+ const state = item.getState();
+ const title = (state.title || "").toLowerCase();
+
+ if (title.startsWith(prefix.toLowerCase())) {
+ await item.archive();
+ }
+ }
+}
+```
+
+## Thread Data
+
+Access thread metadata:
+
+```tsx
+const item = api.threads().item({ id: threadId });
+const state = item.getState();
+
+// {
+// id: "thread-123",
+// remoteId: "remote-123",
+// externalId: "ext-123",
+// title: "Chat about React",
+// status: "regular",
+// }
+```
+
+## Thread Initialization
+
+When using cloud persistence, threads are lazily initialized:
+
+```tsx
+const item = api.threads().item({ id: localThreadId });
+
+// Initialize creates remote mapping
+const { remoteId, externalId } = await item.initialize();
+
+// Now thread is persisted to cloud
+```
+
+## Error Handling
+
+```tsx
+async function safeDelete(threadId: string) {
+ const api = useAui();
+ const item = api.threads().item({ id: threadId });
+
+ try {
+ await item.delete();
+ } catch (error) {
+ if (error.message.includes("not found")) {
+ // Thread already deleted
+ return;
+ }
+ throw error;
+ }
+}
+```
+
+## Sorting and Filtering
+
+Thread list can be sorted by title or by ID for custom ordering:
+
+```tsx
+function SortedThreadList({ sortBy }: { sortBy: "title" | "id" }) {
+ const { threads } = useAuiState((s) => ({ threads: s.threads.threadIds }));
+ const api = useAui();
+
+ const sorted = [...threads].sort((a, b) => {
+ const itemA = api.threads().item({ id: a }).getState();
+ const itemB = api.threads().item({ id: b }).getState();
+
+ if (sortBy === "title") {
+ return (itemA.title || "").localeCompare(itemB.title || "");
+ }
+ return b.localeCompare(a);
+ });
+
+ return (
+
+ {sorted.map((id) => (
+
+ );
+}
+```
+
+## Keyboard Navigation
+
+```tsx
+function KeyboardNav() {
+ const { threads, mainThreadId } = useAuiState((s) => ({
+ threads: s.threads.threadIds,
+ mainThreadId: s.threads.mainThreadId,
+ }));
+ const api = useAui();
+
+ const currentIndex = threads.indexOf(mainThreadId);
+
+ const handleKeyDown = (e: KeyboardEvent) => {
+ if (e.key === "ArrowUp" && currentIndex > 0) {
+ api.threads().switchToThread(threads[currentIndex - 1]);
+ }
+ if (e.key === "ArrowDown" && currentIndex < threads.length - 1) {
+ api.threads().switchToThread(threads[currentIndex + 1]);
+ }
+ };
+
+ useEffect(() => {
+ window.addEventListener("keydown", handleKeyDown);
+ return () => window.removeEventListener("keydown", handleKeyDown);
+ }, [currentIndex, threads]);
+
+ return null;
+}
+```
diff --git a/.agents/skills/tools/SKILL.md b/.agents/skills/tools/SKILL.md
new file mode 100644
index 0000000..92db90c
--- /dev/null
+++ b/.agents/skills/tools/SKILL.md
@@ -0,0 +1,140 @@
+---
+name: tools
+description: Guide for tool registration and tool UI in assistant-ui. Use when implementing LLM tools, tool call rendering, or human-in-the-loop patterns.
+version: 0.0.1
+license: MIT
+---
+
+# assistant-ui Tools
+
+**Always consult [assistant-ui.com/llms.txt](https://assistant-ui.com/llms.txt) for latest API.**
+
+Tools let LLMs trigger actions with custom UI rendering.
+
+## References
+
+- [./references/make-tool.md](./references/make-tool.md) -- makeAssistantTool/useAssistantTool
+- [./references/tool-ui.md](./references/tool-ui.md) -- makeAssistantToolUI rendering
+- [./references/human-in-loop.md](./references/human-in-loop.md) -- Confirmation patterns
+
+## Tool Types
+
+```
+Where does the tool execute?
+├─ Backend (LLM calls API) → AI SDK tool()
+│ └─ Want custom UI? → makeAssistantToolUI
+└─ Frontend (browser-only) → makeAssistantTool
+ └─ Want custom UI? → makeAssistantToolUI
+```
+
+## Backend Tool with UI
+
+```ts
+// Backend (app/api/chat/route.ts)
+import { tool, stepCountIs } from "ai";
+import { z } from "zod";
+
+const tools = {
+ get_weather: tool({
+ description: "Get weather for a city",
+ inputSchema: z.object({ city: z.string() }),
+ execute: async ({ city }) => ({ temp: 22, city }),
+ }),
+};
+
+const result = streamText({
+ model: openai("gpt-4o"),
+ messages,
+ tools,
+ stopWhen: stepCountIs(5),
+});
+```
+
+```tsx
+// Frontend
+import { makeAssistantToolUI } from "@assistant-ui/react";
+
+const WeatherToolUI = makeAssistantToolUI({
+ toolName: "get_weather",
+ render: ({ args, result, status }) => {
+ if (status === "running") return Loading weather...
;
+ return {result?.city}: {result?.temp}°C
;
+ },
+});
+
+// Register in app
+
+
+ );
+ }
+ return Delete {args.path}?
+ + +File deleted
;
+ },
+});
+```
+
+## Common Gotchas
+
+**Tool UI not rendering**
+- `toolName` must match exactly (case-sensitive)
+- Register UI inside `AssistantRuntimeProvider`
+
+**Tool not being called**
+- Check tool description is clear
+- Use `stopWhen: stepCountIs(n)` to allow multi-step
+
+**Result not showing**
+- Tool must return a value
+- Check `status === "complete"` before accessing result
diff --git a/.agents/skills/tools/references/human-in-loop.md b/.agents/skills/tools/references/human-in-loop.md
new file mode 100644
index 0000000..e2dd342
--- /dev/null
+++ b/.agents/skills/tools/references/human-in-loop.md
@@ -0,0 +1,323 @@
+# Human-in-the-Loop Tools
+
+Tools that require user confirmation or input.
+
+## Overview
+
+Human-in-the-loop tools pause execution waiting for user input. Use `status === "requires-action"` to detect this state and `submitResult` to provide the user's response.
+
+## Confirmation Pattern
+
+Ask user to confirm before executing:
+
+```tsx
+// Backend tool returns requires-action status
+const deleteTool = tool({
+ description: "Delete a file (requires user confirmation)",
+ inputSchema: z.object({ path: z.string() }),
+ execute: async ({ path }) => {
+ // Return requires-action to wait for confirmation
+ return { action: "confirm", path };
+ },
+});
+
+// Frontend shows confirmation UI
+const DeleteToolUI = makeAssistantToolUI({
+ toolName: "delete_file",
+ render: ({ args, result, status, submitResult }) => {
+ // Initial state - show confirmation
+ if (status === "requires-action" || !result?.confirmed) {
+ return (
+
+
+ );
+ }
+
+ // After user responds
+ if (result?.confirmed) {
+ return (
+
+
+ Are you sure you want to delete {args.path}?
+
+
+
+
+
+ );
+ }
+
+ return (
+
+ Deletion cancelled
+
+ );
+ },
+});
+```
+
+## Selection Pattern
+
+Let user choose from options:
+
+```tsx
+const SelectToolUI = makeAssistantToolUI({
+ toolName: "select_option",
+ render: ({ args, result, status, submitResult }) => {
+ if (status !== "complete") {
+ return (
+
+
+ );
+ }
+
+ return (
+ {args.prompt}
+
+ {args.options.map((option: any) => (
+
+ ))}
+
+
+ Selected: {args.options.find((o: any) => o.id === result?.selected)?.label}
+
+ );
+ },
+});
+```
+
+## Form Input Pattern
+
+Collect structured data from user:
+
+```tsx
+const FormToolUI = makeAssistantToolUI({
+ toolName: "collect_info",
+ render: ({ args, status, submitResult }) => {
+ const [formData, setFormData] = useState({});
+
+ if (status !== "complete") {
+ return (
+
+ );
+ }
+
+ return Information collected
;
+ },
+});
+```
+
+## Multi-Step Workflow
+
+Chain multiple interactions:
+
+```tsx
+const WizardToolUI = makeAssistantToolUI({
+ toolName: "setup_wizard",
+ render: ({ args, result, status, submitResult }) => {
+ const [step, setStep] = useState(0);
+ const [data, setData] = useState({});
+
+ const steps = args.steps || [];
+ const currentStep = steps[step];
+
+ if (status === "complete") {
+ return Setup complete!
;
+ }
+
+ return (
+
+
+ );
+ },
+});
+```
+
+## Rating/Feedback Pattern
+
+```tsx
+const RatingToolUI = makeAssistantToolUI({
+ toolName: "request_rating",
+ render: ({ args, status, submitResult }) => {
+ const [rating, setRating] = useState(0);
+ const [comment, setComment] = useState("");
+
+ if (status === "complete") {
+ return
+
+
+
+ Step {step + 1} of {steps.length}
+
+ {currentStep.title}
+
+ {currentStep.type === "select" && (
+
+
+ {step > 0 && (
+
+ )}
+
+ {currentStep.options.map((opt: any) => (
+
+ ))}
+
+ )}
+ Thank you for your feedback!
;
+ }
+
+ return (
+
+
{args.prompt}
+ +
+ {[1, 2, 3, 4, 5].map((star) => (
+
+ ))}
+
+
+