ai branches.md
AI Conversation Branches
A chat where editing a message starts a new branch. A small tree beside it shows every version, and you can jump between them.
Installation
npx shadcn@latest add @kokonutui/ai-branches
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title? |
string |
"Trip planning" |
|
messages? |
BranchMessage[] |
demo |
Every message on every branch, read once on mount. Siblings form a fork. |
reply? |
(prompt: string, history: BranchMessage[], signal: AbortSignal) => BranchReply |
demo |
Writes the reply to an edited message. It gets the edit and the messages above it on that branch, and returns the reply, a Promise of it, or a stream of deltas (like the AI SDK's textStream). Throw and the reply shows the error's message. Demo text when omitted. |
onChange? |
(messages: BranchMessage[]) => void |
Every message on every branch, once a new branch's reply is in. | |
className? |
string |
Extra classes for the root element. |
BranchMessage
| Field | Type | Description |
|---|---|---|
id |
string |
|
role |
"user" | "assistant" |
|
text |
string |
|
parent? |
string |
Id of the message this one answers or follows. Leave out for the first. |
BranchReply
A reply: the text, a Promise of it, or a stream of text deltas.
type BranchReply = string | Promise<string> | AsyncIterable<string>;
Usage
Pass your conversation as messages, each with the parent it follows; two messages with the same parent are a fork. Editing a question starts a new branch and calls reply with the edit and the messages above it on that branch. Return the reply, a Promise of it, or a stream of deltas, and it writes in with a caret; a throw shows the error's message. onChange hands you every message once a branch's reply is in, ready to save.
"use client";
import AIBranches, { type BranchMessage } from "@/components/kokonutui/ai-branches";
export function Thread({ messages, save }: { messages: BranchMessage[]; save: (m: BranchMessage[]) => void }) {
return (
<AIBranches
messages={messages}
onChange={save}
reply={async function* (prompt, history, signal) {
const res = await fetch("/api/chat", {
method: "POST",
body: JSON.stringify({
messages: [...history, { role: "user", text: prompt }].map((m) => ({ role: m.role, content: m.text })),
}),
signal,
});
if (!(res.ok && res.body)) {
throw new Error("Couldn't reach the model. Try again.");
}
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
while (true) {
const { done, value } = await reader.read();
if (done) return;
yield value;
}
}}
title="Trip planning"
/>
);
}
The route streams with streamText({ model, messages }).toTextStreamResponse().