/copilotkit-setup

name: copilotkit-setup
description: >
  Use when adding CopilotKit to an existing project or bootstrapping a new CopilotKit
  project from scratch. Covers framework detection, package installation, runtime wiring
  (managed Intelligence or self-hosted SSE), provider setup, and first working chat
  integration.
version: 1.3.0

CopilotKit Setup

Prerequisites

Live Documentation (MCP)

This plugin includes an MCP server (`copilotkit-docs`) that provides `search-docs` and `search-code` tools for querying live CopilotKit documentation and source code.

• **Claude Code:** Auto-configured by the plugin's `.mcp.json` -- no setup needed.
• **Codex:** Requires manual configuration. See the [copilotkit-debug skill](../copilotkit-debug/SKILL.md#mcp-setup) for setup instructions.

Environment

Before starting setup, verify:

1. **Node.js >= 18** (required for `fetch` globals used by the runtime) 2. **An AI provider API key** (one of: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`) 3. **A React-based frontend** (Next.js App Router, Next.js Pages Router, Vite + React, or Angular) 4. **A backend capable of running the runtime** (same Next.js app via API routes, or a standalone Express/Hono server)

Framework Detection

Before generating any code, detect the project's framework by checking files in the project root. See `references/framework-detection.md` for the full decision tree.

**Quick summary:**

| Signal File | Framework | | -------------------------------------------------- | -------------------- | | `next.config.{js,ts,mjs}` + `app/` directory | Next.js App Router | | `next.config.{js,ts,mjs}` + `pages/` directory | Next.js Pages Router | | `angular.json` | Angular | | `vite.config.{js,ts}` + React deps in package.json | Vite + React |

Setup Workflow

Step 1: Install packages

All packages use the `@copilotkit` namespace. The v2 API lives as subpath exports on the published packages.

**Frontend + backend in the same Next.js app:**

npm install @copilotkit/react-core @copilotkit/runtime hono

**Frontend only:**

npm install @copilotkit/react-core

**Backend runtime only:**

npm install @copilotkit/runtime hono

For standalone Express backends, install Express adapter dependencies instead of `hono`:

npm install @copilotkit/runtime express dotenv zod
npm install -D @types/express tsx typescript

(`createCopilotExpressHandler` enables CORS internally, so you do not need to install `cors` yourself. `dotenv` and `zod` are used by the example asset.)

Step 2: Choose a runtime mode, then configure the runtime

The runtime is the server-side component that manages agent execution. See `references/runtime-architecture.md` for details.

**Decide the mode before writing any runtime code.** The mode changes how the runtime is constructed, so retrofitting it later means rewriting this file.

| Mode | Thread state | Choose it when | | -------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------- | | **Managed Intelligence** (recommended) | Durable, hosted | You want threads that survive restarts, hosted ingress, the dashboard, or Channels | | Self-hosted SSE | In-memory, lost on restart | You do not want a hosted dependency and are willing to own persistence yourself |

Ask the user which they want, defaulting to managed Intelligence. State the prerequisites plainly so the choice is informed:

**Managed Intelligence requires** a CopilotKit account (free; `npx copilotkit login` opens the browser) and a project API key. In exchange, threads are durable across restarts and deploys, you get the dashboard, and Slack/Teams Channels become available -- Channels are not available in SSE mode at all.

**Self-hosted SSE requires** nothing beyond an AI provider key. Thread state lives in memory in the process that served the request, so it is lost on restart and is not shared across replicas. Everything in this skill works in SSE mode; it is a supported path, not a dead end.

If the user picks managed Intelligence, use the Intelligence runtime blocks below and then complete Step 6. If they pick SSE, use the SSE blocks and skip Step 6's server-side wiring.

There are two endpoint styles:

1. **Multi-route (Hono)** -- uses `createCopilotHonoHandler`. Requires a catch-all route (`[[...slug]]` in Next.js). Each operation (run, connect, stop, info, transcribe, threads) gets its own HTTP path. 2. **Single-route (Hono or Express)** -- uses `createCopilotHonoHandler({ ..., mode: "single-route" })` or `createCopilotExpressHandler({ ..., mode: "single-route" })`. All operations go through a single POST endpoint with method multiplexing.

Next.js App Router (recommended: multi-route with Hono)

Create `src/app/api/copilotkit/[[...slug]]/route.ts`:

import {
  CopilotRuntime,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
  BuiltInAgent,
} from "@copilotkit/runtime/v2";
import { handle } from "hono/vercel";

const agent = new BuiltInAgent({
  model: "openai/gpt-4o",
  prompt: "You are a helpful AI assistant.",
});

const runtime = new CopilotRuntime({
  agents: {
    default: agent,
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);
// PATCH/DELETE are used by thread operations (useThreads); export them too
// so the multi-route handler can serve them when you enable Intelligence/threads.
export const PATCH = handle(app);
export const DELETE = handle(app);

Next.js App Router with managed Intelligence

Sam