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().