create-bk-agent 0.20.1 → 0.21.1

package/README.md

@@ -1,208 +1,270 @@
 # create-bk-agent
 
-Scaffold a new [BackendKit agent](https://github.com/BackendKit-labs/backendkit-agent-framework) project in seconds — or add capabilities to an existing one.
+CLI scaffolding tool for the BackendKit Labs agent framework. Generates a fully configured TypeScript agent project in seconds — choose your architecture, deployment mode, and LLM provider, and get a working project with all dependencies wired.
 
-## Create a project
+## Usage
 
 ```bash
-npx create-bk-agent my-project
-```
-
-The CLI asks three questions and generates a production-ready project:
+npm create bk-agent@latest my-agent
+cd my-agent && npm install && npm run dev
 
+# Or with npx:
+npx create-bk-agent my-agent
 ```
-✨  create-bk-agent  v0.20.0
 
-? Project name:          my-project
-? Architecture:          Multi-agent (orchestrator + specialists)
-? Skill packs:           Node.js / TypeScript
-? How will it be used?   MCP Server (HTTP)
+---
 
-Creating Multi-agent — MCP Server (HTTP) agent in ./my-project...
-Installing dependencies...
+## Interactive setup
 
-✅  Done! Your agent is ready.
+The CLI asks three questions:
 
-   cd my-project
-   cp .env.example .env      # add your API key
-   npm run server            # starts HTTP MCP on port 3001
-```
+1. **Architecture** — what kind of agent?
+2. **Deploy mode** — how will it be used?
+3. **Provider** — which LLM API?
+
+---
 
 ## Architectures
 
-| Architecture | What it gives you | Best for |
-|---|---|---|
-| `multi-agent` | Orchestrator + specialists with delegation | Domain agents (DevOps, finance, data, etc.) |
-| `single` | One agent with a tool registry | Simple task automation |
-| `coding` | 10 pre-built agents + all coding tools | Coding assistants, ready out of the box |
-| `autonomous` | Trigger system (cron / webhook / event) | Scheduled or event-driven daemons |
-| `minimal` | Bare engine, no entry point | Library embedding |
+### `multi-agent` — Multi-agent orchestrator
 
-## Deploy modes
+A routing orchestrator that delegates tasks to specialized sub-agents. Best for complex domains with distinct request types.
 
-Available for `multi-agent` and `single` architectures:
+```
+src/
+├── agents/         ← agent profiles (JSON)
+├── tools/          ← typed tool definitions
+├── orchestrator.ts ← routes requests to sub-agents
+└── index.ts
+```
 
-| Mode | Entry point | Use case |
-|---|---|---|
-| `repl` | `src/index.ts` — readline loop | Local terminal tool |
-| `mcp-http` | `src/server.ts` — HTTP MCP server | Connect to Claude Desktop, Cursor, etc. |
-| `mcp-stdio` | `src/server.ts` — stdio MCP server | Subprocess / pipe-based MCP |
-| `hybrid` | Both `index.ts` + `server.ts` | REPL for dev, server for production |
-| `library` | Only `src/engine.ts` exported | Import the engine in your own app |
+**Use case:** A customer platform with separate agents for billing, support, and account management.
 
-## Providers
+### `single` — Single-agent assistant
 
-Anthropic (Claude), OpenAI, DeepSeek / any OpenAI-compatible endpoint, and Ollama (local).
+One agent with a custom system prompt and your tools.
 
-## Model configuration
+```
+src/
+├── tools/
+├── agent.ts
+└── index.ts
+```
 
-Generated projects read three env vars for model selection:
+### `coding` — Coding assistant
 
-| Variable | Default | Description |
-|---|---|---|
-| `LLM_MODEL` | `gpt-4o` | Base model — used by all agents unless overridden |
-| `LLM_MODEL_FAST` | `LLM_MODEL` | Execution agents (specialists, tool-calling loops) |
-| `LLM_MODEL_SMART` | `LLM_MODEL` | Routing agents (orchestrator, reasoning-heavy tasks) |
+Pre-configured with 10 coding agents, filesystem tools, persistent memory, and stack detection. Ready to use immediately.
 
-If `LLM_MODEL_FAST` and `LLM_MODEL_SMART` are not set, all agents use `LLM_MODEL` — fully backwards compatible.
+```
+src/
+└── index.ts    ← createCodingEngine() + readline REPL
+AGENT.md        ← project context injected into every LLM call
+```
 
-Example `.env` for DeepSeek with smart/fast split:
+**Use case:** A project-specific coding assistant with your team's conventions in `AGENT.md`.
 
-```env
-LLM_API_KEY=sk-...
-LLM_BASE_URL=https://api.deepseek.com/v1
-LLM_MODEL=deepseek-chat
-LLM_MODEL_FAST=deepseek-chat
-LLM_MODEL_SMART=deepseek-reasoner
-```
+### `autonomous` — Autonomous daemon
 
-The split is wired in `src/engine.ts` — specialists get `llmModelFast`, orchestrator gets `llmModelSmart`. To assign a model directly on a profile instead of via env vars, uncomment the `model:` field in the agent file:
+Runs on a schedule without user interaction. Pre-wired with `createAutonomousAgent` + cron trigger.
 
-```ts
-// src/agents/orchestrator.ts
-export const ORCHESTRATOR_PROFILE: AgentProfile = {
-  id: 'orchestrator',
-  model: 'deepseek-reasoner',  // uncomment and set explicitly
-  ...
-};
+```
+src/
+├── triggers/
+├── tools/
+└── index.ts    ← cron + event loop
 ```
 
----
+**Use case:** Nightly reports, daily standups, automated monitoring.
 
-## Add capabilities to an existing project
+### `minimal` — Minimal / embedded
 
-Once a project is created, use `add` to extend it without editing code manually:
+Bare-bones template — just `AgentEngine`, one tool, one agent. Use when embedding an agent into an existing application or building a library.
 
-```bash
-npx create-bk-agent add <module> [options]
+```
+src/
+└── index.ts    ← AgentEngine, bare minimum
 ```
 
-### `add server` — expose the agent as an HTTP MCP server
+### `enterprise` — Enterprise (local LLM + RAG)
 
-```bash
-npx create-bk-agent add server
-npx create-bk-agent add server --port 4000 --name my-agent
+Full enterprise setup: Ollama LLM, Obsidian vault as knowledge base, six department agents (General, Support, HR, Sales, Finance, Ops), VaultWriter, and optionally an `AgentServer` web server.
+
+```
+src/
+├── server.ts       ← createEnterpriseSetup() + AgentServer
+└── agents/         ← 6 department profiles
+.env.example        ← VAULT_PATH, JWT_SECRET, PORT, OLLAMA_HOST
 ```
 
-- Generates `src/server.ts` wired to the existing engine
-- Adds `@backendkit-labs/mcp-server` to `dependencies`
-- Adds `"server"` script to `package.json`
+---
 
-### `add specialist <name>` — add a specialist agent (multi-agent projects)
+## Deploy modes
 
-```bash
-npx create-bk-agent add specialist data-analyst
-npx create-bk-agent add specialist git-expert
-```
+| Mode | Description |
+|------|-------------|
+| `repl` | Terminal REPL — stdin/stdout |
+| `mcp-stdio` | MCP server over stdio (for Claude Desktop, agent-core) |
+| `mcp-http` | MCP server over HTTP (`npm run server`) |
+| `hybrid` | REPL + MCP server side-by-side |
+| `library` | Exports an engine factory, no I/O |
+| `web` | Fastify web server — chat + kanban (enterprise only) |
 
-- Creates `src/agents/<name>.ts` with an `AgentProfile` stub
-- Patches `src/engine.ts`: adds the import and `agents.register()`
+---
 
-### `add tools <domain>` — add a tool file for a new domain
+## Provider options
 
-```bash
-npx create-bk-agent add tools github
-npx create-bk-agent add tools my-database
-```
+| Provider | Required env var |
+|----------|-----------------|
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| Ollama (local) | *(none — requires `ollama serve`)* |
 
-- Creates `src/tools/<domain>-tools.ts` with two stub tools (action + query)
-- Patches `src/engine.ts`: adds the import and `tools.register()`
+The scaffolded `.env.example` lists all required variables.
 
-### `add mcp-client <url>` — connect to a remote MCP server
+---
 
-```bash
-npx create-bk-agent add mcp-client http://localhost:3001/mcp
-npx create-bk-agent add mcp-client http://billing-agent/mcp --name billing
-```
+## Scaffolded project structure
 
-- Patches `src/engine.ts`: adds the entry to `mcpServers: [...]` inside `AgentEngine`
-- Creates the `mcpServers` array if it doesn't exist yet
+### Coding assistant (simplest)
 
-All `add` commands are **idempotent** — running the same command twice won't duplicate entries.
+```
+my-agent/
+├── src/
+│   └── index.ts      ← createCodingEngine() + readline REPL
+├── AGENT.md          ← project context (edit this!)
+├── package.json
+├── tsconfig.json
+└── .env.example
+```
 
----
+**`AGENT.md`** is injected into every LLM call. Describe your project, stack, and conventions:
 
-## Multi-project workspaces
+```markdown
+# My Project
 
-Group related projects (e.g. microservices) into a workspace so the agent can navigate all of them from a single shared root — no more switching context manually.
+## Tech stack
+Node.js 20, TypeScript 5, Express 4, PostgreSQL 15
 
-### Setup
+## Conventions
+- All functions must have JSDoc
+- Tests use Jest + Supertest
+- Never use `any` — use `unknown`
 
-Use the built-in `/workspace` slash commands from inside the running agent:
+## Architecture
+REST API with repository pattern. DB access only via src/repositories/.
+```
+
+### Enterprise web server (most complete)
 
 ```
-/workspace create my-system
-/workspace add my-system ~/dev/my-system/auth-service
-/workspace add my-system ~/dev/my-system/api-gateway
-/workspace add my-system ~/dev/my-system/user-service
+my-agent/
+├── src/
+│   ├── server.ts         ← createEnterpriseSetup() + AgentServer
+│   └── agents/           ← 6 department profiles
+├── .env.example          ← VAULT_PATH, OLLAMA_HOST, JWT_SECRET, PORT
+├── package.json          ← agent-enterprise + agent-web
+└── tsconfig.json
 ```
 
-When a second project is added, a **common root** is auto-detected (`~/dev/my-system/`). The next `/workspace switch` sets that directory as the agent's working directory, giving it access to all services at once.
+---
+
+## Examples
 
-### Commands
+### Coding assistant
 
-| Command | Description |
-|---|---|
-| `/workspace create <name>` | Create a workspace |
-| `/workspace add <ws> <cwd> [name]` | Add a project |
-| `/workspace import <cwd> [ws] [name]` | Add project (auto-creates workspace) |
-| `/workspace switch <ws> [project]` | Switch to workspace (uses shared root if configured) |
-| `/workspace set-root <ws> [path]` | Set shared root manually (auto-detected if no path) |
-| `/workspace remove <ws> <project>` | Remove a project |
-| `/workspace delete <name>` | Delete workspace |
-| `/workspace list` | List all workspaces |
+```bash
+npx create-bk-agent my-dev-assistant
+# → coding → repl → deepseek
 
-### Shared root (microservices)
+cd my-dev-assistant
+cp .env.example .env
+# Edit .env: add DEEPSEEK_API_KEY
 
-For a system with multiple services under a common parent:
+# Describe your project
+nano AGENT.md
 
-```
-~/dev/my-system/          ← shared root (agent workingDir)
-  ├── auth-service/
-  ├── api-gateway/
-  └── user-service/
+npm install && npm run dev
+# > What can I help with?
 ```
 
-The agent can read and edit files across all services using relative paths:
+### Enterprise on-premises assistant
 
+```bash
+npx create-bk-agent company-assistant
+# → enterprise → web → ollama
+
+cd company-assistant
+cp .env.example .env
+# Edit .env: VAULT_PATH=/path/to/obsidian-vault
+
+ollama serve
+ollama pull llama3.2
+ollama pull nomic-embed-text
+
+npm install && npm run dev
+# → Indexing vault...
+# → Server running on :4001
+# Chat:    http://localhost:4001/
+# Kanban:  http://localhost:4001/#kanban
 ```
-auth-service/src/middleware.ts
-api-gateway/src/routes/auth.ts
+
+### Autonomous cron agent
+
+```bash
+npx create-bk-agent standup-bot
+# → autonomous → repl → deepseek
+
+cd standup-bot
+# Edit src/triggers/index.ts: schedule, prompt, output
+npm install && npm run dev
 ```
 
-To override the auto-detected root:
+### MCP server exposing your tools
+
+```bash
+npx create-bk-agent my-tools-server
+# → single → mcp-http → openai
 
+cd my-tools-server
+# Add tools to src/tools/
+# Add agent to src/agents/
+npm install && npm run server   # MCP server on :3000
 ```
-/workspace set-root my-system ~/dev/my-system
+
+Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "npx",
+      "args": ["-y", "my-tools-server"]
+    }
+  }
+}
 ```
 
 ---
 
-## Requirements
+## `bk add` command
+
+After scaffolding, add new components to your project:
+
+```bash
+bk add tool lookup-order      # creates src/tools/lookup-order.ts
+bk add agent billing          # creates src/agents/billing.json
+bk add trigger daily-report   # adds a cron trigger
+```
 
-- Node.js >= 20
-- An API key for your chosen provider (Anthropic, OpenAI, DeepSeek, or Ollama)
+---
 
-## License
+## Scripts in scaffolded projects
 
-MIT © [BackendKit Labs](https://github.com/BackendKit-labs)
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Development with tsx / ts-node |
+| `npm run build` | Compile TypeScript |
+| `npm run start` | Run compiled output |
+| `npm run server` | Start MCP or web server |
+| `npm run typecheck` | TypeScript type-check only |

package/dist/src/index.js

@@ -65,6 +65,7 @@ function describeChoices(choices) {
         'mcp-stdio': 'MCP Server (stdio)',
         hybrid: 'REPL + MCP Server',
         library: 'Library',
+        web: 'Web Server (chat + kanban)',
     };
     const archLabel = arch[choices.architecture] ?? choices.architecture;
     if (!choices.deployMode)
@@ -83,6 +84,17 @@ function buildNextSteps(choices) {
         return ['Implement your LLM provider in src/index.ts', 'npm run dev'];
     // Enterprise — local LLM + RAG
     if (arch === 'enterprise') {
+        if (mode === 'web') {
+            return [
+                'Make sure Ollama is running:  ollama serve',
+                'Pull model:                   ollama pull llama3.2',
+                'Review vault path in .env (VAULT_PATH)',
+                'npm run dev              # indexes vault + starts server on :4001',
+                '# Chat:    http://localhost:4001/',
+                '# Kanban:  http://localhost:4001/#kanban',
+                '# Monitor: ws://localhost:4001/monitor',
+            ];
+        }
         return [
             'Make sure Ollama is running:  ollama serve',
             'Pull required models:         ollama pull llama3.2 && ollama pull nomic-embed-text',

package/dist/src/prompts.js

@@ -45,7 +45,7 @@ const SKILL_PACK_CHOICES = [
     { title: p('Go', 24) + 'go test, golangci-lint', value: 'go' },
     { title: p('Docker / K8s', 24) + 'docker, kubectl, helm', value: 'docker' },
 ];
-const DEPLOY_MODE_CHOICES = [
+const DEPLOY_MODE_CHOICES_BASE = [
     {
         title: p('Terminal REPL', 28) + 'Humans type requests, agent responds in the terminal',
         value: 'repl',
@@ -68,6 +68,15 @@ const DEPLOY_MODE_CHOICES = [
         value: 'library',
     },
 ];
+const WEB_DEPLOY_CHOICE = {
+    title: p('Web server', 28) + 'WebSocket chat + kanban monitor UI on port 4001',
+    value: 'web',
+    description: 'Serves @backendkit-labs/agent-web with all 6 enterprise departments',
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const deployChoices = (_prev, v) => v.architecture === 'enterprise'
+    ? [...DEPLOY_MODE_CHOICES_BASE, WEB_DEPLOY_CHOICE]
+    : DEPLOY_MODE_CHOICES_BASE;
 const PROVIDER_CHOICES = [
     { title: p('Anthropic (Claude)', 32) + 'claude-sonnet-4-6 recommended', value: 'anthropic' },
     { title: p('OpenAI', 32) + 'gpt-4o recommended', value: 'openai' },
@@ -115,7 +124,7 @@ async function askQuestions(defaultName) {
             type: whenDeploy,
             name: 'deployMode',
             message: 'How will this agent be used?',
-            choices: DEPLOY_MODE_CHOICES,
+            choices: deployChoices,
             initial: 0,
         },
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/src/scaffold.js

@@ -77,6 +77,11 @@ const DEPLOY_SCRIPTS = {
         delete s['server'];
     },
     // hybrid: keep both dev (REPL) and server (MCP) — no changes
+    web: (s) => {
+        s['dev'] = 'ts-node src/server.ts';
+        s['start'] = 'node dist/server.js';
+        delete s['server'];
+    },
     library: (s) => {
         delete s['dev'];
         delete s['server'];
@@ -84,6 +89,7 @@ const DEPLOY_SCRIPTS = {
     },
 };
 const MCP_DEPLOY_MODES = ['mcp-http', 'mcp-stdio', 'hybrid'];
+const WEB_DEPLOY_MODES = ['web'];
 function patchPackageJson(dir, projectName, deployMode) {
     const pkgPath = path.join(dir, 'package.json');
     if (!fs.existsSync(pkgPath))
@@ -98,6 +104,10 @@ function patchPackageJson(dir, projectName, deployMode) {
         pkg.dependencies ??= {};
         pkg.dependencies['@backendkit-labs/mcp-server'] ??= '^0.15.0';
     }
+    if (deployMode && WEB_DEPLOY_MODES.includes(deployMode)) {
+        pkg.dependencies ??= {};
+        pkg.dependencies['@backendkit-labs/agent-web'] ??= '^0.1.0';
+    }
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
 }
 // ── Write .env stub ───────────────────────────────────────────────────────────
@@ -165,10 +175,10 @@ function scaffold(choices, targetDir) {
     // 2. Deploy layer — overlaid on top of base (layered architectures only)
     if (isLayered && choices.deployMode && choices.deployMode !== 'library') {
         const deployDir = path.join(DEPLOY_DIR, choices.deployMode);
-        if (!fs.existsSync(deployDir)) {
-            throw new Error(`Deploy template not found: ${choices.deployMode} (in ${deployDir})`);
+        if (fs.existsSync(deployDir)) {
+            copyDir(deployDir, targetDir);
         }
-        copyDir(deployDir, targetDir);
+        // No directory = base template already covers this mode
     }
     // 3. Skill packs — appended to engine.ts
     for (const pack of choices.skillPacks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bk-agent",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "description": "Create a new BackendKit agent project",
   "main": "dist/src/index.js",
   "bin": {