@tanstack/ai-octane

Octane hooks for TanStack AI. They work like the React hooks. To build your first chat, start with the Quick Start. For a typed chat layout, see Octane Chat UI.

Installation#

npm i @tanstack/ai-octane octane

pnpm add @tanstack/ai-octane octane

yarn add @tanstack/ai-octane octane

bun add @tanstack/ai-octane octane

octane is a required peer. The package publishes uncompiled .tsrx source, and your Octane plugin compiles it.

useChat(options)#

Holds the messages and the run state of one chat, and talks to your server route.

import { useState } from "octane";
import { useChat, fetchServerSentEvents } from "@tanstack/ai-octane";

export function Chat() {
  const [input, setInput] = useState("");
  const { messages, sendMessage, isLoading } = useChat({
    connection: fetchServerSentEvents("/api/chat"),
    threadId: "support-chat",
  });

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          <strong>{message.role}:</strong>
          {message.parts
            .filter((part) => part.type === "text")
            .map((part) => part.content)
            .join("")}
        </div>
      ))}
      <input
        value={input}
        onInput={(event) => setInput(event.currentTarget.value)}
      />
      <button
        disabled={isLoading}
        onClick={() => {
          void sendMessage(input);
          setInput("");
        }}
        type="button"
      >
        Send
      </button>
    </div>
  );
}

Options#

You must pass threadId. You must also pass connection or fetcher, not both.

The hook also takes the ChatClient callbacks (onResponse, onChunk, onFinish, onError, onInterruptStateChange, onCustomEvent) and the other client options. See ChatClient options.

When connection, fetcher, forwardedProps, tools, context, or queue change, the hook updates the current chat. A new threadId creates a new chat.

Returns#

State values are plain Octane values. The hook renders again when they change.

Example: tool approval#

A tool with needsApproval: true pauses the run. The pending call shows up in interrupts.

import { toolDefinition } from "@tanstack/ai";
import { useChat, fetchServerSentEvents } from "@tanstack/ai-octane";
import { z } from "zod";

const deleteFileTool = toolDefinition({
  name: "delete_file",
  description: "Delete a file",
  needsApproval: true,
  inputSchema: z.object({ path: z.string() }),
});

export function ChatWithApproval() {
  const { interrupts } = useChat({
    connection: fetchServerSentEvents("/api/chat"),
    threadId: "support-chat",
    tools: [deleteFileTool],
  });

  return (
    <div>
      {interrupts.map((interrupt) =>
        interrupt.kind === "tool-approval" ? (
          <div key={interrupt.id}>
            <p>Approve: {interrupt.toolName}</p>
            <button onClick={() => interrupt.resolveInterrupt(true)} type="button">
              Approve
            </button>
            <button onClick={() => interrupt.resolveInterrupt(false)} type="button">
              Deny
            </button>
          </div>
        ) : null,
      )}
    </div>
  );
}

See Tool Approval for the server side.

createChatHook(options)#

Binds chat options once at module scope and returns a useChat hook that uses them.

import { createChatHook, fetchServerSentEvents } from "@tanstack/ai-octane";

const { useChat: useSupportChat } = createChatHook({
  connection: fetchServerSentEvents("/api/chat"),
});

export function SupportScreen() {
  const chat = useSupportChat({ threadId: "support-1" });
  return <p>{chat.messages.length} messages</p>;
}

The bound hook takes these per-call overrides: threadId, initialMessages, live, and forwardedProps. Keep tools, interrupts, and outputSchema on the factory options.

@tanstack/ai-octane/ui has its own createChatHook that also returns typed UI components. See Octane Chat UI.

Generation hooks#

Each hook runs one generation request and keeps its result. See Generation Hooks.

import { useGenerateImage, fetchServerSentEvents } from "@tanstack/ai-octane";

export function ImageButton() {
  const image = useGenerateImage({
    connection: fetchServerSentEvents("/api/generate/image"),
    threadId: "image-studio",
  });

  return (
    <button
      disabled={image.isLoading}
      onClick={() => void image.generate({ prompt: "A mountain at sunset" })}
      type="button"
    >
      Generate
    </button>
  );
}

Options: threadId (required), connection or fetcher, body, devtools, onResult, onError, onProgress, onChunk.

Returns: generate(input), result, isLoading, error, status, stop(), and reset().

useGenerateVideo also returns jobId and videoStatus, and takes onJobCreated and onStatusUpdate.

useRealtimeChat(options)#

Runs a voice conversation with a realtime model. Pass getToken and adapter. See Realtime Chat.

import { useRealtimeChat } from "@tanstack/ai-octane";
import { openaiRealtime } from "@tanstack/ai-openai";

export function VoiceChat() {
  const chat = useRealtimeChat({
    getToken: () => fetch("/api/realtime-token").then((r) => r.json()),
    adapter: openaiRealtime(),
  });

  return chat.status === "idle" ? (
    <button onClick={() => void chat.connect()} type="button">Start</button>
  ) : (
    <button onClick={() => void chat.disconnect()} type="button">Stop</button>
  );
}

Returns status, error, mode, messages, connect(), disconnect(), startListening(), stopListening(), interrupt(), sendText(text), sendImage(data, mimeType), updateSession(config), plus audio levels and frequency data for visualizers.

useAudioRecorder(options?)#

Records audio from the microphone. See Audio Recording.

Returns recording, isRecording, isSupported, start(), stop(), and cancel(). Pass onComplete to transform the recording. Then recording and stop() use the transformed type.

BYOK#

This package does not export a BYOK hook. Read the keyring with byok.getSnapshot() and byok.subscribe(listener). BYOK helpers (defineByok, defaultByokStorage, and more) are on the @tanstack/ai-octane/byok subpath. See Bring Your Own Key.

useMcpAppBridge(options)#

Returns a stable MCP App bridge for one thread. It always calls the latest chat.sendMessage and onLink. Options: threadId, callEndpoint, chat, fetchImpl, onLink. See MCP Apps.

This package has no mcp-apps subpath, so it does not ship the MCPAppResource component.

useRegisterWebMCPTools(tools, options?)#

Exposes client tools to the browser WebMCP API while the component is mounted. See WebMCP Tools.

import { useRegisterWebMCPTools } from "@tanstack/ai-octane";
import { searchProducts } from "./tools";

const tools = [searchProducts];

export function ProductsPage() {
  useRegisterWebMCPTools(tools, {
    onError: (error) => console.error(error),
  });
  return null;
}

Options: toolOptions, context, and onError. context is required when a tool declares a required runtime context. The hook registers the tools again when tools or options change, so keep them stable.

usePageWebMCPTools(options?)#

Reads the WebMCP tools that the page registered, as client tools. The array starts empty and updates when the page adds or removes a tool. Pass it to useChat as tools. See Page WebMCP Tools in Chat.

import { usePageWebMCPTools } from "@tanstack/ai-octane";

export function useSameOriginPageTools() {
  return usePageWebMCPTools({
    filter: (tool) => tool.origin === location.origin,
  });
}

Options: filter (return false to skip a tool) and onError.

Re-exports from @tanstack/ai-client#

You can import these from @tanstack/ai-octane directly. See @tanstack/ai-client for details.

The browser persistence adapters (localStoragePersistence and the others) are not re-exported here. Import them from @tanstack/ai-client.

Types#

Pass a plain tools array to useChat or createChatClientOptions. Tool names, inputs, and outputs stay typed without as const. Import toolDefinition from @tanstack/ai.