vercel · bensabic · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -38,9 +38,11 @@ pnpm --filter chat build
 pnpm --filter @chat-adapter/slack build
 pnpm --filter @chat-adapter/gchat build
 pnpm --filter @chat-adapter/teams build
+pnpm --filter create-bot build
 
 # Run tests for a specific package
 pnpm --filter chat test
+pnpm --filter create-bot test
 pnpm --filter @chat-adapter/integration-tests test
 
 # Run a single test file
@@ -65,6 +67,7 @@ This is a **pnpm monorepo** using **Turborepo** for build orchestration. All pac
 - **`packages/state-memory`** - In-memory state adapter (for development/testing)
 - **`packages/state-redis`** - Redis state adapter (for production)
 - **`packages/adapter-whatsapp`** - WhatsApp adapter using Meta Cloud API
+- **`packages/create-bot`** - `create-bot` CLI for scaffolding new Chat SDK bot projects
 - **`packages/integration-tests`** - Integration tests against real platform APIs
 - **`examples/nextjs-chat`** - Example Next.js app showing how to use the SDK
 

diff --git a/apps/docs/content/docs/contributing/building.mdx b/apps/docs/content/docs/contributing/building.mdx
@@ -36,6 +36,10 @@ Chat SDK ships with Vercel-maintained adapters for Slack, Teams, Google Chat, Di
 - Documentation of the adapter in primary vendor docs.
 - Announcement of the adapter in blog post or changelog and social media.
 
+<Callout type="info">
+  Vendor official adapters are also included in the [`create-bot`](/docs/create-bot) CLI and co-marketing opportunities may be available.
+</Callout>
+
 ## Project setup
 
 This guide uses a hypothetical **Matrix** adapter as a running example. Replace "matrix" with your platform name throughout.

diff --git a/apps/docs/content/docs/create-bot.mdx b/apps/docs/content/docs/create-bot.mdx
@@ -0,0 +1,86 @@
+---
+title: create-bot
+description: Scaffold a new Chat SDK bot project with a single command.
+---
+
+`create-bot` is the fastest way to start a new Chat SDK project. It scaffolds a Next.js app with your chosen platform adapters, state adapter, environment variables, and webhook route — ready to run.
+
+## Quick start
+
+```bash tab="npm"
+npx create-bot my-bot
+```
+
+```bash tab="pnpm"
+pnpm create bot my-bot
+```
+
+```bash tab="yarn"
+yarn create bot my-bot
+```
+
+```bash tab="bun"
+bunx create-bot my-bot
+```
+
+The CLI walks you through selecting platform adapters (Slack, Teams, Discord, etc.) and a state adapter (Redis, PostgreSQL, or in-memory), then installs dependencies automatically.
+
+## What you get
+
+```
+my-bot/
+  src/
+    lib/bot.ts                              # Bot config with your adapters and handlers
+    app/api/webhooks/[platform]/route.ts    # Dynamic webhook route for all platforms
+  .env.example                              # Pre-populated environment variables
+  next.config.ts                            # Next.js config with serverExternalPackages
+  package.json                              # Dependencies for your selected adapters
+  tsconfig.json                             # TypeScript config with Chat SDK JSX runtime
+```
+
+The generated `bot.ts` includes starter handlers for `onNewMention` and `onSubscribedMessage` so you can start testing immediately.
+
+## Non-interactive usage
+
+Every prompt can be skipped with flags, making `create-bot` fully scriptable for CI, automation, and AI agents:
+
+```bash
+npx create-bot my-bot -d 'My bot' --adapter slack teams redis -yq
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `-d, --description <text>` | Project description |
+| `--adapter <values...>` | Platform or state adapters to include (skips interactive prompt) |
+| `--pm <manager>` | Package manager to use (`npm`, `yarn`, `pnpm`, `bun`) |
+| `-y, --yes` | Skip confirmation prompts (accept defaults) |
+| `-q, --quiet` | Suppress non-essential output |
+| `--no-color` | Disable color output (respects `NO_COLOR`) |
+
+### Available adapter values
+
+**Messaging Platforms:** `slack`, `teams`, `gchat`, `discord`, `telegram`, `whatsapp`, `matrix`, `imessage`, `zernio`
+
+**Developer Tools:** `github`, `linear`, `resend`, `liveblocks`
+
+**State:** `memory`, `redis`, `ioredis`, `pg`
+
+## After scaffolding
+
+1. Copy the example environment file and fill in your platform credentials:
+
+```bash
+cp .env.example .env.local
+```
+
+2. Start the dev server:
+
+```bash
+npm run dev
+```
+
+3. Expose your local server (e.g. with [ngrok](https://ngrok.com)) and configure your platform's webhook URL to `https://<your-url>/api/webhooks/<platform>`.
+
+See the [platform adapter docs](/docs/adapters) for setup instructions specific to each platform.
diff --git a/apps/docs/content/docs/getting-started.mdx b/apps/docs/content/docs/getting-started.mdx
@@ -3,6 +3,14 @@ title: Getting Started
 description: Pick a guide to start building with Chat SDK.
 ---
 
+## Scaffold a new project
+
+The fastest way to get started is with `create-bot`. It scaffolds a complete Next.js bot project with your chosen adapters, environment variables, and webhook route.
+
+<Cards>
+  <Card title="create-bot" description="Scaffold a new Chat SDK bot project with a single command." href="/docs/create-bot" />
+</Cards>
+
 ## Usage
 
 Learn the core patterns for handling incoming events and posting messages back to your users.

diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx
@@ -18,6 +18,16 @@ Building a chat bot that works across multiple platforms typically means maintai
 - **AI streaming** with first-class support for streaming LLM responses
 - **Serverless-ready** with distributed state via Redis and message deduplication
 
+## Quick start
+
+The fastest way to start a new project is with `create-bot`:
+
+```bash
+npx create-bot my-bot
+```
+
+This scaffolds a Next.js app with your chosen adapters, environment variables, and a webhook route — ready to run. See the [create-bot docs](/docs/create-bot) for all options.
+
 ## How it works
 
 Chat SDK has three core concepts:

diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json
@@ -3,6 +3,7 @@
   "pages": [
     "index",
     "getting-started",
+    "create-bot",
     "---Usage---",
     "usage",
     "threads-messages-channels",

diff --git a/biome.jsonc b/biome.jsonc
@@ -29,6 +29,7 @@
   "files": {
     "includes": [
       "**/*",
+      "!packages/create-bot/_template",
       "!apps/docs/app/\\[lang\\]/docs",
       "!apps/docs/app/\\[lang\\]/llms.mdx",
       "!apps/docs/app/\\[lang\\]/llms.txt",

diff --git a/knip.json b/knip.json
@@ -2,7 +2,7 @@
   "$schema": "https://unpkg.com/knip@5/schema.json",
   "ignoreBinaries": ["vercel"],
   "ignoreDependencies": ["@biomejs/biome"],
-  "ignore": ["apps/docs/**/*"],
+  "ignore": ["apps/docs/**/*", "packages/create-bot/_template/**/*"],
   "rules": {
     "duplicates": "off",
     "types": "off"

diff --git a/packages/create-bot/AGENTS.md b/packages/create-bot/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md
+
+`create-bot` is a CLI tool that scaffolds new [Chat SDK](https://chat-sdk.dev) bot projects.
+
+## Commands
+
+```bash
+pnpm --filter create-bot build       # Build with tsup
+pnpm --filter create-bot typecheck   # Type-check
+pnpm --filter create-bot test        # Run tests with coverage
+pnpm -w run check                    # Lint and format (monorepo-wide)
+pnpm validate                        # Full validation (build, typecheck, lint, test)
+```
+
+## Docs
+
+- [CLI documentation](../../apps/docs/content/docs/create-bot.mdx)
+- [Full Chat SDK docs](../../apps/docs/content/docs)
+- [Architecture](./ARCHITECTURE.md) for detailed structure, data flow, and design decisions.
diff --git a/packages/create-bot/ARCHITECTURE.md b/packages/create-bot/ARCHITECTURE.md
@@ -0,0 +1,81 @@
+# Architecture
+
+`create-bot` is a CLI that scaffolds new [Chat SDK](https://chat-sdk.dev) bot projects. It is published as the `create-bot` npm package and lives in the Chat SDK monorepo at `packages/create-bot`.
+
+## Project structure
+
+```
+packages/create-bot/
+├── src/
+│   ├── index.ts          # Entry point — calls createProgram().parse()
+│   ├── cli.ts            # Commander program definition, flags, help text
+│   ├── prompts.ts        # Interactive prompts (Clack) and flag resolution
+│   ├── scaffold.ts       # File copying, post-processing, dependency install
+│   ├── templates.ts      # Dynamic code generation (bot.ts)
+│   └── types.ts          # Shared TypeScript interfaces
+├── _template/            # Static template files copied into scaffolded projects
+│   ├── src/app/api/webhooks/[platform]/route.ts
+│   ├── .agents/skills/chat-sdk/SKILL.md
+│   ├── AGENTS.md
+│   ├── README.md
+│   ├── .env.example
+│   ├── .gitignore
+│   ├── next.config.ts
+│   ├── tsconfig.json
+│   └── package.json
+├── adapters.json         # Adapter registry (platforms, state, env vars, categories)
+├── AGENTS.md             # Agent instructions for this package
+├── ARCHITECTURE.md       # This document
+├── CLAUDE.md             # Points to AGENTS.md
+├── tsup.config.ts        # Bundler config (ESM + shebang)
+├── vitest.config.ts      # Test config with v8 coverage
+└── package.json
+```
+
+## Data flow
+
+```
+CLI invocation (npx create-bot my-bot --adapter slack redis)
+  │
+  ▼
+index.ts ──► cli.ts (Commander parses args and flags)
+                │
+                ▼
+           prompts.ts (resolves flags or runs interactive Clack prompts)
+                │
+                ├── resolveAdapterFlags()  ← matches --adapter values to adapters.json
+                ├── text / groupMultiselect / select / confirm  ← interactive fallback
+                └── detectPackageManager()  ← reads npm_config_user_agent
+                │
+                ▼
+           scaffold.ts (creates the project on disk)
+                │
+                ├── copyDir()              ← copies _template/ → project directory
+                ├── postProcessEnvExample  ← injects adapter env vars into .env.example
+                ├── postProcessNextConfig  ← adds serverExternalPackages if needed
+                ├── npm pkg set            ← sets name, description, adapter dependencies
+                ├── templates.botTs()      ← generates src/lib/bot.ts with imports + handlers
+                └── execa(install)         ← runs package manager install
+                │
+                ▼
+           cli.ts (displays next steps and outro)
+```
+
+## Key design decisions
+
+- **Static template + post-processing**: Most files live as-is in `_template/` and are copied verbatim. Only `.env.example`, `next.config.ts`, and `package.json` are post-processed. `src/lib/bot.ts` is the sole fully-generated file because its imports and adapter configuration vary per selection.
+- **`adapters.json` as registry**: All adapter metadata (packages, factory functions, env vars, categories, server external packages) is centralized in a single JSON file. The CLI reads it at build time via an import assertion. This avoids hardcoding adapter knowledge across multiple source files.
+- **`npm pkg set` for `package.json`**: Instead of generating the full `package.json` from a template function, the CLI copies a base `package.json` from `_template/` and patches it with `npm pkg set`. This keeps the base file readable and avoids JSON serialization edge cases.
+- **Clack for interactive UX**: `@clack/prompts` provides the interactive prompt flow with spinners, grouped multi-select, and cancellation handling. All prompts are skippable via flags for non-interactive / CI usage.
+- **Commander for arg parsing**: Handles positional args, flags, help text generation, and the `--no-color` convention.
+
+## Testing
+
+Tests use Vitest with v8 coverage. Each source module has a co-located `.test.ts` file. The test strategy:
+
+- **`cli.test.ts`** — Mocks `runPrompts` and `scaffold`; tests Commander program creation, help text output, and action handler logic.
+- **`prompts.test.ts`** — Mocks `@clack/prompts`; tests interactive flows, flag resolution, cancellation, validation, and package manager detection.
+- **`scaffold.test.ts`** — Uses real temp directories; mocks `execa` and `@clack/prompts`; tests file copying, post-processing, dependency installation, and overwrite prompts.
+- **`templates.test.ts`** — Pure function tests for `botTs()` output with various adapter combinations.
+
+`types.ts` and `index.ts` are excluded from coverage — `types.ts` is definition-only and `index.ts` is a one-line entry point.
diff --git a/packages/create-bot/CLAUDE.md b/packages/create-bot/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md