claude-code-controller 0.3.0 → 0.5.0

package/README.md

@@ -18,8 +18,7 @@
 
 <br />
 
-> Control real Claude Code instances through a **REST API**, a **TypeScript SDK**, or a **Web Dashboard**.
-> Spawn agents, send them messages, assign tasks, approve plans — from your code or your browser.
+> **Three lines of code.** Ask Claude a question, get an answer. Spin up persistent agents for multi-turn conversations. Orchestrate entire teams of agents working in parallel. All running **real Claude Code** — the same one you use in your terminal every day.
 
 <br />
 
@@ -27,53 +26,69 @@
 
 <br />
 
-## Why this instead of the Agent SDK?
+## Quick Start
 
-This runs **real Claude Code processes**. Not a wrapper around the API. Not a simplified `-p` mode. Actual Claude Code — the same one you use in your terminal every day.
+```bash
+npm install claude-code-controller
+```
 
-That means:
+> **Prerequisite:** [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) v2.1.34+
 
-- **Uses your Claude Code subscription** — No separate API key. No usage-based billing surprise. If you have a Max plan, your agents run on it.
-- **Day 0 features** — When Anthropic ships a new Claude Code feature (new tools, new models, better context handling), you get it immediately. No library update needed. No waiting for SDK support.
-- **Full tool access** — Bash, Read, Write, Edit, Glob, Grep, WebSearch, Task sub-agents... everything Claude Code can do, your agents can do.
-- **Real terminal environment** — Agents run in a PTY. They can install packages, run tests, use git, call APIs. They work in your actual project directory.
-- **Battle-tested agent loop** — Claude Code's agent loop is production-hardened. You get all of that for free: retries, error handling, tool orchestration, context management.
+<br />
+
+### One-liner — ask a question, get an answer
+
+```typescript
+import { claude } from "claude-code-controller";
+
+const answer = await claude("What does this project do?", { model: "sonnet" });
+console.log(answer);
+```
+
+That's it. No initialization, no boilerplate, no `sleep()` hacks. The agent is created, responds, and cleans up automatically.
 
 <br />
 
----
+### Persistent agent — multi-turn conversations
+
+```typescript
+const agent = await claude.agent({ model: "sonnet", cwd: "/my/project" });
+
+const review = await agent.ask("Review src/auth.ts for security issues");
+const fixes = await agent.ask("Now fix the issues you found");
+
+await agent.close();
+```
+
+The agent retains full context between calls. Ask follow-up questions, build on previous answers, iterate on a task — like pairing with a colleague.
 
 <br />
 
-## What you can do
+### Multi-agent session — parallel teams
+
+```typescript
+const session = await claude.session({ model: "sonnet" });
 
-**Spawn multiple agents on the same codebase**, each with a different role. One reviews security, another writes tests, another refactors — all in parallel, all through a simple API.
+const reviewer = await session.agent("reviewer", { model: "opus" });
+const coder = await session.agent("coder");
 
-```bash
-# Spawn an agent via the REST API
-curl -X POST http://localhost:3000/agents \
-  -H "Content-Type: application/json" \
-  -d '{"name": "security-reviewer", "model": "opus"}'
+const issues = await reviewer.ask("Review src/ for security vulnerabilities");
+await coder.ask(`Fix these issues:\n${issues}`);
 
-# Give it work
-curl -X POST http://localhost:3000/agents/security-reviewer/messages \
-  -H "Content-Type: application/json" \
-  -d '{"message": "Audit src/auth/ for vulnerabilities. Reply with SendMessage."}'
+await session.close();
 ```
 
-**Build automation on top of Claude Code.** A webhook that triggers a code fix when CI fails. A Slack bot that assigns tasks to agents. A cron job that runs nightly code reviews. If you can make an HTTP call, you can control Claude Code.
+Each agent has its own process, its own context, its own model. They work in parallel on your codebase. One reviews, another codes, another writes tests — all at the same time.
 
-**Monitor and control agents from a web dashboard.** See what each agent is doing, approve or reject their plans, grant tool permissions, kill runaway agents — all in real-time from your browser.
+<br />
 
-**Manage work with tasks.** Create tasks, assign them to agents, track progress, define dependencies between tasks. Agents pick up their assignments and report back when done.
+### Auto-cleanup with `await using`
 
 ```typescript
-const taskId = await ctrl.createTask({
-  subject: "Add input validation to all API routes",
-  description: "Use zod schemas for request body validation in src/routes/",
-});
-await ctrl.assignTask(taskId, "coder");
-await ctrl.waitForTask(taskId); // blocks until done
+{
+  await using agent = await claude.agent({ model: "sonnet" });
+  const answer = await agent.ask("What is 2+2?");
+} // agent.close() called automatically
 ```
 
 <br />
@@ -82,16 +97,17 @@ await ctrl.waitForTask(taskId); // blocks until done
 
 <br />
 
-## Features
+## Why this instead of the Agent SDK?
 
-- **REST API** — Control everything over HTTP. Spawn agents, send messages, manage tasks. Works from any language, any platform.
-- **TypeScript SDK** — Full programmatic control with type safety and an event-driven architecture.
-- **Web Dashboard** — Real-time monitoring, agent management, and interactive approvals from your browser.
-- **Multi-Agent** — Run multiple agents in parallel, each with their own role, model, and permissions.
-- **Task Management** — Create tasks, assign them, track status, define blocking dependencies.
-- **Plan & Permission Approval** — Agents ask before acting. You approve or reject — programmatically or from the UI.
-- **Any Provider** — Point agents at any Anthropic-compatible endpoint. Per-agent environment and API key overrides.
-- **Your Subscription** — Runs on your existing Claude Code plan. No separate API costs.
+This runs **real Claude Code processes**. Not a wrapper around the API. Not a simplified `-p` mode. Actual Claude Code — the same one you use in your terminal every day.
+
+That means:
+
+- **Uses your Claude Code subscription** — No separate API key needed. No usage-based billing surprise. If you have a Max plan, your agents run on it.
+- **Day 0 features** — When Anthropic ships a new Claude Code feature (new tools, new models, better context handling), you get it immediately. No library update needed. No waiting for SDK support.
+- **Full tool access** — Bash, Read, Write, Edit, Glob, Grep, WebSearch, Task sub-agents... everything Claude Code can do, your agents can do.
+- **Real terminal environment** — Agents run in a PTY. They can install packages, run tests, use git, call APIs. They work in your actual project directory.
+- **Battle-tested agent loop** — Claude Code's agent loop is production-hardened. You get all of that for free: retries, error handling, tool orchestration, context management.
 
 <br />
 
@@ -99,13 +115,19 @@ await ctrl.waitForTask(taskId); // blocks until done
 
 <br />
 
-## Install
-
-```bash
-npm install claude-code-controller
-```
+## Features
 
-> **Prerequisite:** [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) v2.1.34+
+- **3 lines of code** — From zero to a working agent in seconds. No boilerplate, no two-step initialization.
+- **Multi-turn conversations** — Persistent agents that remember context across `ask()` calls.
+- **Multi-agent sessions** — Orchestrate teams of agents working in parallel on the same codebase.
+- **Permission control** — Four presets from full-access to ask-before-every-tool. Auto-approve, allowlists, or inline callbacks.
+- **First-class API key support** — Pass `apiKey` and `baseUrl` directly. No env var wiring.
+- **REST API** — Control everything over HTTP. Works from any language, any platform.
+- **Web Dashboard** — Real-time monitoring, agent management, and interactive approvals from your browser.
+- **Task management** — Create tasks, assign them to agents, track progress, define blocking dependencies.
+- **`await using` support** — Automatic cleanup with `Symbol.asyncDispose`.
+- **Any provider** — Point agents at any Anthropic-compatible endpoint. Per-agent overrides.
+- **Your subscription** — Runs on your existing Claude Code plan. No separate API costs.
 
 <br />
 
@@ -113,28 +135,78 @@ npm install claude-code-controller
 
 <br />
 
-## Quick Start — 30 seconds to your first agent
+## Permission Control
+
+Every agent gets a permission preset that controls what tools it can use without asking.
+
+| Preset | Behavior |
+|--------|----------|
+| `"full"` (default) | All tools, no approval needed |
+| `"edit"` | Auto-approve read/write/bash |
+| `"plan"` | Read-only exploration |
+| `"ask"` | Fires events for every tool use |
 
 ```typescript
-import { ClaudeCodeController } from "claude-code-controller";
+// Full access (default)
+const agent = await claude.agent({ permissions: "full" });
 
-const ctrl = new ClaudeCodeController({ teamName: "my-project" });
-await ctrl.init();
+// Read-only explorer
+const agent = await claude.agent({ permissions: "plan" });
 
-const agent = await ctrl.spawnAgent({
-  name: "coder",
-  model: "sonnet",
+// Ask-mode with auto-approve for safe tools
+const agent = await claude.agent({
+  permissions: "ask",
+  autoApprove: ["Read", "Glob", "Grep"],
 });
 
-await new Promise((r) => setTimeout(r, 10_000));
+// Auto-approve everything (YOLO mode)
+const agent = await claude.agent({
+  permissions: "ask",
+  autoApprove: true,
+});
+```
 
-const answer = await agent.ask(
-  "Read package.json and tell me the project name. Reply using SendMessage.",
-  { timeout: 60_000 }
-);
-console.log(answer);
+<br />
+
+### Inline callbacks
+
+Handle permission and plan requests with simple callbacks:
 
-await ctrl.shutdown();
+```typescript
+const agent = await claude.agent({
+  permissions: "ask",
+  onPermission: (req) => {
+    console.log(`Tool: ${req.toolName} — ${req.description}`);
+    req.toolName === "Bash" ? req.reject() : req.approve();
+  },
+  onPlan: (req) => {
+    console.log("Plan:", req.planContent);
+    req.approve();
+  },
+});
+```
+
+<br />
+
+### Event-based
+
+Or use the event emitter pattern for more control:
+
+```typescript
+const agent = await claude.agent({ permissions: "ask" });
+
+agent.on("permission", (req) => {
+  const safe = ["Read", "Glob", "Grep"].includes(req.toolName);
+  safe ? req.approve() : req.reject();
+});
+
+agent.on("plan", (req) => {
+  req.approve();
+});
+
+agent.on("message", (text) => console.log(text));
+agent.on("error", (err) => console.error(err));
+agent.on("exit", (code) => console.log("Agent exited:", code));
 ```
 
 <br />
@@ -145,34 +217,40 @@ await ctrl.shutdown();
 
 ## REST API
 
-The API lets you control Claude Code agents from **any language, any platform** — just HTTP.
+Control Claude Code agents from **any language, any platform** — just HTTP.
+
+<br />
 
-Start a server in a few lines:
+### Start a server
 
 ```typescript
 import { createApi } from "claude-code-controller/api";
-import { serve } from "bun"; // or any Hono-compatible runtime
 
-const app = createApi(); // lazy mode — init via POST /session/init
-serve({ port: 3000, fetch: app.fetch.bind(app) });
+const app = createApi();
+Bun.serve({ port: 3000, fetch: app.fetch });
 ```
 
-Or attach to an existing controller:
-
-```typescript
-import { ClaudeCodeController } from "claude-code-controller";
-import { createApi } from "claude-code-controller/api";
+<br />
 
-const ctrl = new ClaudeCodeController({ teamName: "my-team" });
-await ctrl.init();
+### One-liner over HTTP
 
-const app = createApi(ctrl); // pre-initialized mode
+```bash
+curl -X POST http://localhost:3000/ask \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "What does this project do?", "model": "sonnet"}'
+# → { "response": "This project is a..." }
 ```
 
 <br />
 
 ### Endpoints
 
+#### Ask (one-liner)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/ask` | Send a prompt, get a response. Creates an ephemeral agent. |
+
 #### Session
 
 | Method | Endpoint | Description |
@@ -192,8 +270,7 @@ const app = createApi(ctrl); // pre-initialized mode
 | `POST` | `/agents/:name/messages` | Send a message to an agent |
 | `POST` | `/agents/:name/kill` | Force-kill an agent |
 | `POST` | `/agents/:name/shutdown` | Request graceful shutdown |
-| `POST` | `/agents/:name/approve-plan` | Approve or reject a plan |
-| `POST` | `/agents/:name/approve-permission` | Approve or deny tool use |
+| `POST` | `/agents/:name/approve` | Approve or reject a plan or permission request |
 
 #### Tasks
 
@@ -206,44 +283,31 @@ const app = createApi(ctrl); // pre-initialized mode
 | `DELETE` | `/tasks/:id` | Delete a task |
 | `POST` | `/tasks/:id/assign` | Assign task to an agent |
 
-#### Actions (for dashboards & UIs)
+#### Actions & Broadcasting
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | `GET` | `/actions` | All pending actions (approvals, idle agents, unassigned tasks) |
-| `GET` | `/actions/approvals` | Pending approval requests |
-| `GET` | `/actions/tasks` | Unassigned tasks |
-| `GET` | `/actions/idle-agents` | Idle agents waiting for work |
-
-#### Broadcasting
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
 | `POST` | `/broadcast` | Send a message to all agents |
 
 <br />
 
 ### API Examples
 
-**Initialize a session:**
+**Initialize a session with API key:**
 
 ```bash
 curl -X POST http://localhost:3000/session/init \
   -H "Content-Type: application/json" \
-  -d '{"teamName": "my-team", "cwd": "/path/to/project"}'
+  -d '{"teamName": "my-team", "apiKey": "sk-ant-...", "baseUrl": "https://api.example.com"}'
 ```
 
-**Spawn an agent:**
+**Spawn an agent with permissions:**
 
 ```bash
 curl -X POST http://localhost:3000/agents \
   -H "Content-Type: application/json" \
-  -d '{
-    "name": "reviewer",
-    "type": "general-purpose",
-    "model": "sonnet",
-    "permissions": ["Bash", "Read", "Write"]
-  }'
+  -d '{"name": "reviewer", "model": "opus", "permissions": "edit"}'
 ```
 
 **Send a message:**
@@ -251,7 +315,7 @@ curl -X POST http://localhost:3000/agents \
 ```bash
 curl -X POST http://localhost:3000/agents/reviewer/messages \
   -H "Content-Type: application/json" \
-  -d '{"message": "Review src/auth.ts for security vulnerabilities. Reply with SendMessage."}'
+  -d '{"message": "Review src/auth.ts for security vulnerabilities"}'
 ```
 
 **Create and assign a task:**
@@ -268,148 +332,40 @@ curl -X POST http://localhost:3000/tasks/1/assign \
   -d '{"agent": "reviewer"}'
 ```
 
-**Check pending actions:**
-
-```bash
-curl http://localhost:3000/actions
-# → { "pending": 2, "approvals": [...], "unassignedTasks": [...], "idleAgents": [...] }
-```
-
 <br />
 
 ---
 
 <br />
 
-## TypeScript SDK
-
-The SDK gives you full programmatic control with type safety and an event-driven architecture.
-
-### Controller
-
-```typescript
-import { ClaudeCodeController } from "claude-code-controller";
-
-const ctrl = new ClaudeCodeController({
-  teamName: "my-team",        // auto-generated if omitted
-  cwd: "/path/to/project",    // working directory for agents
-  claudeBinary: "claude",     // path to CLI binary
-  env: {                      // default env vars for all agents
-    ANTHROPIC_BASE_URL: "https://your-proxy.example.com",
-  },
-  logLevel: "info",           // "debug" | "info" | "warn" | "error" | "silent"
-});
-
-await ctrl.init();
-// ... use the controller ...
-await ctrl.shutdown();
-```
-
-### Spawning Agents
-
-```typescript
-const agent = await ctrl.spawnAgent({
-  name: "coder",
-  type: "general-purpose",   // "general-purpose" | "Bash" | "Explore" | "Plan"
-  model: "sonnet",           // "sonnet" | "opus" | "haiku" | full model ID
-  cwd: "/specific/directory",
-  permissions: ["Bash", "Read", "Write", "Glob", "Grep"],
-  env: { MY_VAR: "value" },  // per-agent env overrides
-});
-```
-
-### AgentHandle
-
-Every spawned agent returns an `AgentHandle` — a convenient wrapper for interacting with it.
-
-```typescript
-// Send and receive
-await agent.send("Analyze the codebase structure.");
-const response = await agent.receive({ timeout: 30_000 });
-
-// Or use ask() for send + receive in one call
-const answer = await agent.ask("What framework is this project using?", {
-  timeout: 60_000,
-});
+## Web Dashboard
 
-// Stream events
-for await (const msg of agent.events()) {
-  console.log(`[${agent.name}]`, msg.text);
-}
+A built-in web UI for real-time agent management — no code required.
 
-// Lifecycle
-agent.isRunning;    // boolean
-agent.pid;          // process ID
-await agent.shutdown();  // graceful
-await agent.kill();      // force
+```bash
+cd web && bun install
 ```
 
-### Messaging
-
-```typescript
-// Direct messaging
-await ctrl.send("agent-name", "Your instructions here", "optional summary");
-
-// Broadcast to all agents
-await ctrl.broadcast("Everyone stop and report status.");
-
-// Wait for a response
-const messages = await ctrl.receive("agent-name", {
-  timeout: 60_000,
-  pollInterval: 500,
-  all: true,          // get all unread messages
-});
+**Development:**
 
-// Wait for any agent to respond
-const msg = await ctrl.receiveAny({ timeout: 30_000 });
+```bash
+bun run dev          # backend on :3456
+bun run dev:vite     # frontend on :5174
 ```
 
-### Task Management
-
-```typescript
-// Create a task
-const taskId = await ctrl.createTask({
-  subject: "Add input validation",
-  description: "Add zod schemas to all API endpoints in src/routes/",
-  owner: "coder",           // optional — assign immediately
-  metadata: { priority: "high" },
-});
-
-// Assign later
-await ctrl.assignTask(taskId, "coder");
+**Production:**
 
-// Wait for completion
-const task = await ctrl.waitForTask(taskId, 120_000);
-console.log(task.status); // "completed"
+```bash
+bun run build && bun run start   # everything on :3456
 ```
 
-### Events
-
-```typescript
-// Agent messages
-ctrl.on("message", (agentName, message) => {
-  console.log(`[${agentName}] ${message.text}`);
-});
-
-// Plan approval — agent wants to execute a plan
-ctrl.on("plan:approval_request", (agentName, msg) => {
-  console.log(`${agentName} wants to execute a plan:`, msg.planContent);
-  ctrl.sendPlanApproval(agentName, msg.requestId, true);
-});
-
-// Permission request — agent wants to use a tool
-ctrl.on("permission:request", (agentName, msg) => {
-  const safe = ["Read", "Glob", "Grep"].includes(msg.toolName);
-  ctrl.sendPermissionResponse(agentName, msg.requestId, safe);
-});
+The dashboard gives you:
 
-// Lifecycle events
-ctrl.on("agent:spawned", (name, pid) => console.log(`${name} started (pid: ${pid})`));
-ctrl.on("agent:exited", (name, code) => console.log(`${name} exited (code: ${code})`));
-ctrl.on("idle", (name) => console.log(`${name} is idle`));
-ctrl.on("task:completed", (task) => console.log(`Task done: ${task.subject}`));
-ctrl.on("error", (err) => console.error("Controller error:", err));
-```
+- **Session management** — Initialize with API key, base URL, team name, and working directory
+- **Agent spawning** — Configure name, type, model, and permission level from a dropdown
+- **Live message feed** — Real-time messages via WebSocket
+- **Approval prompts** — Interactive plan and permission approval banners
+- **Agent controls** — Shutdown or kill agents individually
 
 <br />
 
@@ -422,134 +378,174 @@ ctrl.on("error", (err) => console.error("Controller error:", err));
 ### Parallel Code Review
 
 ```typescript
-const ctrl = new ClaudeCodeController({ teamName: "review" });
-await ctrl.init();
+import { claude } from "claude-code-controller";
+
+const session = await claude.session({ model: "sonnet" });
 
 const [security, perf, style] = await Promise.all([
-  ctrl.spawnAgent({ name: "security", model: "opus" }),
-  ctrl.spawnAgent({ name: "perf", model: "sonnet" }),
-  ctrl.spawnAgent({ name: "style", model: "haiku" }),
+  session.agent("security", { model: "opus" }),
+  session.agent("perf"),
+  session.agent("style", { model: "haiku" }),
 ]);
 
-await new Promise((r) => setTimeout(r, 12_000));
-
 const reviews = await Promise.all([
-  security.ask("Review src/ for security vulnerabilities. Reply with SendMessage."),
-  perf.ask("Review src/ for performance issues. Reply with SendMessage."),
-  style.ask("Review src/ for code style issues. Reply with SendMessage."),
+  security.ask("Review src/ for security vulnerabilities"),
+  perf.ask("Review src/ for performance issues"),
+  style.ask("Review src/ for code style issues"),
 ]);
 
 console.log("Security:", reviews[0]);
 console.log("Performance:", reviews[1]);
 console.log("Style:", reviews[2]);
 
-await ctrl.shutdown();
+await session.close();
 ```
 
 ### Task-Based Workflow
 
 ```typescript
-const ctrl = new ClaudeCodeController({ teamName: "tasks" });
-await ctrl.init();
+import { claude, Session } from "claude-code-controller";
 
-const worker = await ctrl.spawnAgent({ name: "worker", model: "sonnet" });
-await new Promise((r) => setTimeout(r, 10_000));
+const session = await claude.session({ model: "sonnet" });
+const worker = await session.agent("worker");
 
-const taskId = await ctrl.createTask({
+// Create and assign a task via the underlying controller
+const taskId = await session.controller.createTask({
   subject: "Add input validation",
   description: "Add zod validation to all API route handlers in src/routes/",
   owner: "worker",
 });
 
-const result = await ctrl.waitForTask(taskId, 120_000);
+const result = await session.controller.waitForTask(taskId, 120_000);
 console.log(`Task ${result.status}: ${result.subject}`);
 
-await ctrl.shutdown();
+await session.close();
 ```
 
 ### Custom API Provider
 
 ```typescript
-const ctrl = new ClaudeCodeController({
-  teamName: "custom",
-  env: {
-    ANTHROPIC_BASE_URL: "https://your-proxy.example.com/api/anthropic",
-    ANTHROPIC_AUTH_TOKEN: process.env.MY_API_KEY!,
-  },
+const agent = await claude.agent({
+  model: "sonnet",
+  apiKey: "sk-ant-...",
+  baseUrl: "https://your-proxy.example.com/api/anthropic",
 });
 
-// Per-agent overrides
-const agent = await ctrl.spawnAgent({
-  name: "worker",
-  env: { ANTHROPIC_AUTH_TOKEN: "different-key-for-this-agent" },
-});
+const answer = await agent.ask("What framework is this project using?");
+await agent.close();
 ```
 
-### Auto-Approve Everything (YOLO mode)
+### Selective Permission Control
 
 ```typescript
-ctrl.on("plan:approval_request", (agent, msg) => {
-  ctrl.sendPlanApproval(agent, msg.requestId, true);
-});
-
-ctrl.on("permission:request", (agent, msg) => {
-  ctrl.sendPermissionResponse(agent, msg.requestId, true);
+const agent = await claude.agent({
+  permissions: "ask",
+  onPermission: (req) => {
+    const safe = ["Read", "Glob", "Grep", "Task"].includes(req.toolName);
+    const review = ["Bash", "Write", "Edit"].includes(req.toolName);
+
+    if (safe) {
+      req.approve();
+    } else if (review) {
+      console.log(`[REVIEW] ${req.toolName}: ${req.description}`);
+      req.approve(); // or implement your own review logic
+    } else {
+      req.reject();
+    }
+  },
 });
 ```
 
-### Selective Permission Control
+<br />
+
+---
+
+<br />
+
+## Advanced: Full Controller
+
+The simplified API is built on top of `ClaudeCodeController` — a full-featured class that gives you direct access to the teammate protocol. Use it when you need low-level control over team configuration, inbox polling, or process management.
 
 ```typescript
-const SAFE_TOOLS = ["Read", "Glob", "Grep", "Task"];
-const NEEDS_REVIEW = ["Bash", "Write", "Edit"];
+import { ClaudeCodeController } from "claude-code-controller";
 
-ctrl.on("permission:request", (agent, msg) => {
-  if (SAFE_TOOLS.includes(msg.toolName)) {
-    ctrl.sendPermissionResponse(agent, msg.requestId, true);
-  } else if (NEEDS_REVIEW.includes(msg.toolName)) {
-    console.log(`[REVIEW] ${agent} wants to use ${msg.toolName}: ${msg.description}`);
-    // Implement your own review logic here
-    ctrl.sendPermissionResponse(agent, msg.requestId, true);
-  } else {
-    ctrl.sendPermissionResponse(agent, msg.requestId, false);
-  }
+const ctrl = new ClaudeCodeController({
+  teamName: "my-team",
+  cwd: "/path/to/project",
+  env: {
+    ANTHROPIC_BASE_URL: "https://your-proxy.example.com",
+    ANTHROPIC_AUTH_TOKEN: "sk-ant-...",
+  },
+  logLevel: "info",
 });
+
+await ctrl.init();
 ```
 
-<br />
+### Spawning Agents
 
----
+```typescript
+const agent = await ctrl.spawnAgent({
+  name: "coder",
+  type: "general-purpose",
+  model: "sonnet",
+  permissionMode: "bypassPermissions",
+  env: { MY_VAR: "value" },
+});
+```
 
-<br />
+### AgentHandle
 
-## Web Dashboard
+```typescript
+await agent.send("Analyze the codebase structure.");
+const response = await agent.receive({ timeout: 30_000 });
 
-A built-in web UI for real-time agent management — no code required.
+const answer = await agent.ask("What framework is this project using?", {
+  timeout: 60_000,
+});
 
-```bash
-cd web && bun install
+agent.isRunning;         // boolean
+agent.pid;               // process ID
+await agent.shutdown();  // graceful
+await agent.kill();      // force
 ```
 
-**Development:**
+### Messaging
 
-```bash
-bun run dev          # backend on :3456
-bun run dev:vite     # frontend on :5174
+```typescript
+await ctrl.send("agent-name", "Your instructions here");
+await ctrl.broadcast("Everyone stop and report status.");
+const msg = await ctrl.receiveAny({ timeout: 30_000 });
 ```
 
-**Production:**
+### Task Management
 
-```bash
-bun run build && bun run start   # everything on :3456
+```typescript
+const taskId = await ctrl.createTask({
+  subject: "Add input validation",
+  description: "Add zod schemas to all API endpoints",
+  owner: "coder",
+});
+
+await ctrl.assignTask(taskId, "coder");
+const task = await ctrl.waitForTask(taskId, 120_000);
 ```
 
-The dashboard gives you:
+### Events
 
-- **Session management** — Initialize and shut down the controller
-- **Agent spawning** — Configure name, type, model, and environment variables
-- **Live message feed** — Real-time messages via WebSocket
-- **Approval prompts** — Interactive plan and permission approval banners
-- **Agent controls** — Shutdown or kill agents individually
+```typescript
+ctrl.on("message", (agent, msg) => console.log(`[${agent}] ${msg.text}`));
+ctrl.on("plan:approval_request", (agent, msg) => {
+  ctrl.sendPlanApproval(agent, msg.requestId, true);
+});
+ctrl.on("permission:request", (agent, msg) => {
+  ctrl.sendPermissionResponse(agent, msg.requestId, true);
+});
+ctrl.on("agent:spawned", (name, pid) => console.log(`${name} started`));
+ctrl.on("agent:exited", (name, code) => console.log(`${name} exited`));
+ctrl.on("idle", (name) => console.log(`${name} is idle`));
+ctrl.on("task:completed", (task) => console.log(`Done: ${task.subject}`));
+```
 
 <br />
 
@@ -603,7 +599,7 @@ ClaudeCodeController
 
 ```bash
 bun install          # install deps
-bun test             # run tests (89 tests)
+bun test             # run tests
 bun run typecheck    # type check
 bun run build        # build for distribution
 ```
@@ -614,19 +610,6 @@ bun run build        # build for distribution
 
 <br />
 
-## Roadmap
-
-- **Tmux session per agent** — Spawn each agent in its own tmux pane. Attach with `tmux attach -t <agent>` and watch it work: tool calls, file edits, reasoning — like watching someone use Claude Code interactively.
-- **Task management in the UI** — Create, assign, and track tasks from the web dashboard.
-- **Agent-to-agent messaging** — Let agents communicate directly with each other.
-- **Persistent sessions** — Resume a team session after server restart.
-
-<br />
-
----
-
-<br />
-
 ## License
 
 MIT