Threads

Connect your CopilotKit runtime to the Enterprise Intelligence Platform. This provides the thread storage and WebSocket infrastructure. Thread names are automatically generated by the LLM after the first message — you can disable this with `generateThreadNames: false`.

```typescript title="server.ts"
import { CopilotRuntime } from "@copilotkit/runtime";

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  // Thread names are auto-generated by default.
  // Set to false to disable:
  // generateThreadNames: false,

  // Optional: tune thread lock behavior
  // lockTtlSeconds: 20,              // Lock TTL (default 20s, max 3600s)
  // lockHeartbeatIntervalSeconds: 15, // Heartbeat interval (default 15s, max 3000s)
  // lockKeyPrefix: "my-app",          // Custom Redis key prefix for the lock
});
```

If you're using Copilot Cloud, thread storage is handled automatically. For self-hosted deployments, see [Self-Hosting Intelligence](/premium/self-hosting) for the Helm chart install and database configuration.

Use the `useThreads` hook to fetch and manage threads for a specific agent. The hook returns the thread list, loading state, and mutation methods.

```tsx title="ThreadSidebar.tsx"
import { useThreads } from "@copilotkit/react-core/v2"; // [!code highlight]

function ThreadSidebar() {
  const { // [!code highlight:6]
    threads,
    isLoading,
    renameThread,
    archiveThread,
    deleteThread,
  } = useThreads({ agentId: "my-agent" });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {threads.map((thread) => (
        <div key={thread.id}>
          <span>{thread.name ?? "New conversation"}</span>
          <button onClick={() => renameThread(thread.id, "Renamed")}>
            Rename
          </button>
          <button onClick={() => archiveThread(thread.id)}>
            Archive
          </button>
        </div>
      ))}
    </div>
  );
}
```

The `threads` array is sorted by most recently updated first and stays synchronized in realtime — new threads from other tabs or devices appear automatically.

**Archive vs. delete:** `archiveThread` is a soft delete — the thread stays in the database but is hidden from the list by default. Pass `includeArchived: true` to show archived threads. `deleteThread` is permanent and irreversible. Neither has a built-in confirmation dialog — add your own if needed.

When a user selects a thread, pass its `threadId` to your chat component. The chat clears the current messages, fetches the selected thread's history, and replays it. If the agent is still running on that thread, the chat picks up the live stream.

```tsx title="App.tsx"
import { CopilotChat } from "@copilotkit/react-core/v2"; // [!code highlight]
import { useState } from "react";

function App() {
  const [activeThreadId, setActiveThreadId] = useState<string | undefined>();

  return (
    <div className="flex">
      <ThreadSidebar onSelectThread={setActiveThreadId} />
      <CopilotChat threadId={activeThreadId} />
    </div>
  );
}
```

When `threadId` changes, the chat component automatically loads the selected thread's history and reconnects to the agent's stream. If the agent is still running on that thread, the chat picks up the live stream.

For users with many conversations, use the `limit` parameter to enable cursor-based pagination.

```tsx title="ThreadSidebar.tsx"
const {
  threads,
  hasMoreThreads,
  isFetchingMoreThreads,
  fetchMoreThreads,
} = useThreads({
  agentId: "my-agent",
  limit: 20, // [!code highlight]
});

// In your JSX:
{hasMoreThreads && (
  <button
    onClick={fetchMoreThreads}
    disabled={isFetchingMoreThreads}
  >
    {isFetchingMoreThreads ? "Loading..." : "Load more"}
  </button>
)}
```