botholomew 0.7.9 → 0.7.11

package/README.md

@@ -6,6 +6,8 @@
   " "
 ```
 
+![Botholomew chat TUI](docs/assets/chat-happy-path.gif)
+
 **A local-first AI agent for knowledge work.** Botholomew is a long-running
 autonomous agent that works its way through a task queue — reading email,
 summarizing documents, researching topics, organizing notes, and maintaining
@@ -111,6 +113,8 @@ Everything the agent can touch is here. No surprises.
 
 ## The CLI
 
+![CLI walkthrough: task list, task add, schedule list, context list](docs/assets/cli-tour.gif)
+
 | Command | Purpose |
 |---|---|
 | `botholomew init` | Create `.botholomew/` with templates and a fresh database |
@@ -193,6 +197,8 @@ Topics worth understanding in detail:
   multi-project service naming.
 - **[Configuration](docs/configuration.md)** — every key in `config.json`
   and its default.
+- **[Doc captures](docs/captures.md)** — how the screenshots and GIFs in
+  these docs are regenerated programmatically via VHS and a fake-LLM mode.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "description": "Local, autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {
@@ -19,7 +19,8 @@
     "dev": "bun run src/cli.ts",
     "dev:demo": "bun run src/cli.ts chat -p 'learn everything you can about me from the connected MCP services and then save what you'\\''ve learned about me to context'",
     "test": "bun test",
-    "lint": "tsc --noEmit && biome check ."
+    "lint": "tsc --noEmit && biome check .",
+    "capture": "bun run scripts/capture.ts"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.88.0",

package/src/chat/agent.ts

@@ -1,4 +1,3 @@
-import Anthropic from "@anthropic-ai/sdk";
 import type {
   MessageParam,
   ToolResultBlockParam,
@@ -9,6 +8,7 @@ import type { BotholomewConfig } from "../config/schemas.ts";
 import { embedSingle } from "../context/embedder.ts";
 import { fitToContextWindow, getMaxInputTokens } from "../daemon/context.ts";
 import { maybeStoreResult } from "../daemon/large-results.ts";
+import { createLlmClient } from "../daemon/llm-client.ts";
 import {
   buildMetaHeader,
   extractKeywords,
@@ -178,9 +178,7 @@ export async function runChatTurn(input: {
     callbacks,
   } = input;
 
-  const client = new Anthropic({
-    apiKey: config.anthropic_api_key || undefined,
-  });
+  const client = createLlmClient(config);
 
   const chatTools = getChatTools();
   const maxInputTokens = await getMaxInputTokens(

package/src/commands/chat.ts

@@ -36,6 +36,12 @@ export function registerChatCommand(program: Command) {
           await ensureDaemonRunning(dir);
         }
 
+        // VHS/ttyd doesn't fully negotiate the Kitty Keyboard protocol, so
+        // Ink's "enabled" mode drops non-text keystrokes (Tab, Escape) under
+        // capture. Use "disabled" mode in capture to keep text input working;
+        // captures that need Tab/Escape should use the `-p` prompt flag or
+        // a /slash command typed as text instead.
+        const isCapture = process.env.BOTHOLOMEW_FAKE_LLM === "1";
         const instance = render(
           React.createElement(App, {
             projectDir: dir,
@@ -44,10 +50,12 @@ export function registerChatCommand(program: Command) {
           }),
           {
             exitOnCtrlC: false,
-            kittyKeyboard: {
-              mode: "enabled",
-              flags: ["disambiguateEscapeCodes"],
-            },
+            kittyKeyboard: isCapture
+              ? { mode: "disabled" }
+              : {
+                  mode: "enabled",
+                  flags: ["disambiguateEscapeCodes"],
+                },
           },
         );
         await instance.waitUntilExit();

package/src/commands/context.ts

@@ -25,6 +25,7 @@ import {
   createContextItemStrict,
   deleteContextItemByPath,
   getContextItemByPath,
+  getContextItemBySourcePath,
   listContextItems,
   listContextItemsByPrefix,
   PathConflictError,
@@ -193,9 +194,126 @@ export function registerContextCommand(program: Command) {
           text: `Found ${totalCount} item(s) to add (${filesToAdd.length} file(s), ${urlsToAdd.length} URL(s)).`,
         });
 
-        // Phase 1.5: LLM placement for files without an explicit path
         const config = await loadConfig(dir);
         const CONCURRENCY = 10;
+
+        // Phase 0: Source-path dedup — items whose source_path is already in
+        // context are routed per --on-conflict before we pay for LLM placement.
+        type AlreadyInContext = {
+          sourcePath: string;
+          sourceType: "file" | "url";
+          existing: ContextItem;
+        };
+        const alreadyInContext: AlreadyInContext[] = [];
+        const remainingFiles: FileToAdd[] = [];
+        const remainingUrls: { url: string; contextPath: string }[] = [];
+
+        for (const f of filesToAdd) {
+          const existing = await getContextItemBySourcePath(
+            conn,
+            f.filePath,
+            "file",
+          );
+          if (existing) {
+            alreadyInContext.push({
+              sourcePath: f.filePath,
+              sourceType: "file",
+              existing,
+            });
+          } else {
+            remainingFiles.push(f);
+          }
+        }
+        for (const u of urlsToAdd) {
+          const existing = await getContextItemBySourcePath(conn, u.url, "url");
+          if (existing) {
+            alreadyInContext.push({
+              sourcePath: u.url,
+              sourceType: "url",
+              existing,
+            });
+          } else {
+            remainingUrls.push(u);
+          }
+        }
+
+        let refreshedCount = 0;
+        let refreshedChunks = 0;
+        const dedupSkipped: string[] = [];
+
+        if (alreadyInContext.length > 0) {
+          if (policy === "error") {
+            logger.error(
+              `${alreadyInContext.length} item(s) already in context (matched by source path):`,
+            );
+            for (const a of alreadyInContext) {
+              console.log(
+                `  ${ansis.red("✗")} ${a.sourcePath} → ${a.existing.context_path} (id: ${a.existing.id})`,
+              );
+            }
+            logger.dim(
+              "Re-run with --on-conflict=skip to ignore these items or --on-conflict=overwrite to refresh them from disk.",
+            );
+            process.exit(1);
+          }
+
+          if (policy === "skip") {
+            for (const a of alreadyInContext) {
+              logger.dim(
+                `⊘ already in context: ${a.sourcePath} → ${a.existing.context_path}`,
+              );
+              dedupSkipped.push(a.existing.context_path);
+            }
+          } else {
+            // overwrite: refresh existing items (diff + selective re-embed),
+            // preserving their original context_path.
+            const itemsToRefresh = alreadyInContext.map((a) => a.existing);
+            const hasUrls = itemsToRefresh.some((i) => i.source_type === "url");
+            const mcpxClient = hasUrls ? await createMcpxClient(dir) : null;
+
+            const refreshSpinner = createSpinner(
+              `Refreshing 0/${itemsToRefresh.length} existing item(s)...`,
+            ).start();
+            const refreshResult = await refreshContextItems(
+              conn,
+              itemsToRefresh,
+              config,
+              mcpxClient,
+              {
+                onItemProgress: (done, total) => {
+                  refreshSpinner.update({
+                    text: `Refreshing ${done}/${total} existing item(s)...`,
+                  });
+                },
+              },
+            );
+            refreshSpinner.success({
+              text: `Refreshed ${refreshResult.checked} existing item(s): ${refreshResult.updated} updated, ${refreshResult.unchanged} unchanged, ${refreshResult.missing} missing.`,
+            });
+
+            // Count everything we processed OK (updated + unchanged) as
+            // "refreshed" for the summary. Missing/error items are reported
+            // inline below and don't count toward success.
+            refreshedCount = refreshResult.updated + refreshResult.unchanged;
+            refreshedChunks = refreshResult.chunks;
+            for (const item of refreshResult.items) {
+              if (item.status === "missing") {
+                logger.warn(`  Missing: ${item.source_path}`);
+              } else if (item.status === "error") {
+                logger.warn(
+                  `  Error refreshing ${item.source_path}: ${item.error}`,
+                );
+              }
+            }
+          }
+        }
+
+        // Drop already-handled items from the work lists so downstream phases
+        // (LLM placement, description, insert, embed) see only truly-new items.
+        filesToAdd.splice(0, filesToAdd.length, ...remainingFiles);
+        urlsToAdd.splice(0, urlsToAdd.length, ...remainingUrls);
+
+        // Phase 1.5: LLM placement for files without an explicit path
         const needsPlacement = filesToAdd.filter((f) => f.contextPath === null);
         // description cache keyed by filePath — populated when LLM placement runs,
         // reused in addFile to avoid a second describe call.
@@ -378,10 +496,13 @@ export function registerContextCommand(program: Command) {
           }
         }
 
-        // Report conflicts before embeddings so the user sees them prominently
+        // Report conflicts before embeddings so the user sees them prominently.
+        // Phase 0 already handled source-path matches, so anything here is a
+        // target-path collision — an LLM-suggested (or explicit) path that
+        // another unrelated item already occupies.
         if (conflicts.length > 0) {
           logger.error(
-            `${conflicts.length} path collision(s) — nothing written for these items:`,
+            `${conflicts.length} target-path collision(s) — nothing written for these items:`,
           );
           for (const c of conflicts) {
             console.log(
@@ -389,24 +510,34 @@ export function registerContextCommand(program: Command) {
             );
           }
           logger.dim(
-            "Re-run with --on-conflict=overwrite to replace, --on-conflict=skip to ignore, or --name / --prefix to place elsewhere.",
+            "The suggested path is already in use by a different source. Re-run with --prefix to place these items elsewhere, or delete the existing item first.",
           );
         }
 
+        // Merge Phase 0 skips into the skip list used by the final summary.
+        skipped.push(...dedupSkipped);
+
         // Phase 3: Chunk + embed in parallel (network I/O)
         if (itemIds.length === 0 || !config.openai_api_key) {
           if (!config.openai_api_key) {
             logger.dim("Skipping embeddings (no OpenAI API key configured).");
           }
-          const msg = `Added ${itemIds.length}/${totalCount} item(s), 0 chunks indexed.`;
+          const msg = buildSummary({
+            added: itemIds.length,
+            refreshed: refreshedCount,
+            skipped: skipped.length,
+            chunks: refreshedChunks,
+            totalCount,
+            handled: itemIds.length + refreshedCount + skipped.length,
+          });
           if (conflicts.length > 0) {
             logger.error(msg);
             process.exit(1);
           }
-          if (itemIds.length === totalCount - skipped.length) {
+          if (itemIds.length + skipped.length + refreshedCount >= totalCount) {
             logger.success(msg);
             process.exit(0);
-          } else if (itemIds.length === 0) {
+          } else if (itemIds.length === 0 && refreshedCount === 0) {
             logger.error(msg);
             process.exit(1);
           } else {
@@ -452,15 +583,20 @@ export function registerContextCommand(program: Command) {
           else filesAdded++;
         }
 
-        const parts: string[] = [];
-        if (filesAdded > 0) parts.push(`${filesAdded} added`);
-        if (filesUpdated > 0) parts.push(`${filesUpdated} updated`);
-        const summary = `${parts.join(", ")} — ${chunks} chunk(s) indexed (${itemIds.length}/${totalCount} item(s)).`;
+        const summary = buildSummary({
+          added: filesAdded,
+          updated: filesUpdated,
+          refreshed: refreshedCount,
+          skipped: skipped.length,
+          chunks: chunks + refreshedChunks,
+          totalCount,
+          handled: itemIds.length + refreshedCount + skipped.length,
+        });
         if (conflicts.length > 0) {
           logger.error(summary);
           process.exit(1);
         }
-        if (itemIds.length === totalCount - skipped.length) {
+        if (itemIds.length + skipped.length + refreshedCount >= totalCount) {
           logger.success(summary);
           process.exit(0);
         } else {
@@ -675,6 +811,26 @@ async function resolveItems(
 
 type ConflictPolicy = "error" | "overwrite" | "skip";
 
+/** Format the final "X added, Y refreshed, Z skipped — N chunks" line. */
+function buildSummary(args: {
+  added: number;
+  updated?: number;
+  refreshed: number;
+  skipped: number;
+  chunks: number;
+  totalCount: number;
+  handled?: number;
+}): string {
+  const parts: string[] = [];
+  if (args.added > 0) parts.push(`${args.added} added`);
+  if (args.updated && args.updated > 0) parts.push(`${args.updated} updated`);
+  if (args.refreshed > 0) parts.push(`${args.refreshed} refreshed`);
+  if (args.skipped > 0) parts.push(`${args.skipped} skipped`);
+  const body = parts.length > 0 ? parts.join(", ") : "0 added";
+  const handled = args.handled ?? args.added + args.refreshed + args.skipped;
+  return `${body} — ${args.chunks} chunk(s) indexed (${handled}/${args.totalCount} item(s)).`;
+}
+
 type AddFileResult =
   | { kind: "added"; id: string; contextPath: string }
   | { kind: "skipped"; contextPath: string }

package/src/daemon/fake-llm.ts

@@ -0,0 +1,204 @@
+import { EventEmitter } from "node:events";
+import { existsSync, readFileSync } from "node:fs";
+import type Anthropic from "@anthropic-ai/sdk";
+import type {
+  Message,
+  ToolUseBlock,
+} from "@anthropic-ai/sdk/resources/messages";
+
+export interface FakeTurn {
+  /** Optional regex matched against the most recent user-authored text. */
+  match?: string;
+  /** Full reply text; auto-chunked if `chunks` is absent. */
+  text?: string;
+  /** Explicit token chunks; overrides auto-chunking. */
+  chunks?: string[];
+  /** Characters per auto-chunk when `chunks` is absent. */
+  chunkSize?: number;
+  /** Delay between chunks in milliseconds. */
+  delayMs?: number;
+  /** Optional tool calls to emit after text. */
+  toolCalls?: Array<{
+    id?: string;
+    name: string;
+    input: Record<string, unknown>;
+  }>;
+}
+
+export interface FakeFixture {
+  turns: FakeTurn[];
+}
+
+let loadedFixture: FakeFixture | null = null;
+let loadedFixturePath: string | undefined;
+let sequentialIndex = 0;
+
+function loadFixture(): FakeFixture {
+  const fixturePath = process.env.BOTHOLOMEW_FAKE_LLM_FIXTURE;
+  // Reload (and reset the sequential cursor) whenever the fixture path
+  // changes — tests rotate fixtures between cases, and callers can swap
+  // fixtures mid-session without restarting the process.
+  if (loadedFixture && loadedFixturePath === fixturePath) {
+    return loadedFixture;
+  }
+  loadedFixturePath = fixturePath;
+  sequentialIndex = 0;
+  if (!fixturePath) {
+    loadedFixture = { turns: [] };
+    return loadedFixture;
+  }
+  if (!existsSync(fixturePath)) {
+    throw new Error(
+      `BOTHOLOMEW_FAKE_LLM_FIXTURE points to missing file: ${fixturePath}`,
+    );
+  }
+  loadedFixture = JSON.parse(readFileSync(fixturePath, "utf8")) as FakeFixture;
+  return loadedFixture;
+}
+
+function selectTurn(lastUserText: string): FakeTurn {
+  const fixture = loadFixture();
+  if (fixture.turns.length === 0) {
+    return { text: "(fake LLM: no fixture turns configured)" };
+  }
+  // Only consider turns at or after the cursor, so that multi-turn fixtures
+  // (e.g. text → tool_use → follow-up text) advance past a matched turn even
+  // when the agent's next iteration shows the same user text.
+  for (let i = sequentialIndex; i < fixture.turns.length; i++) {
+    const t = fixture.turns[i];
+    if (t?.match && new RegExp(t.match, "i").test(lastUserText)) {
+      sequentialIndex = i + 1;
+      return t;
+    }
+  }
+  if (sequentialIndex < fixture.turns.length) {
+    const t = fixture.turns[sequentialIndex];
+    sequentialIndex++;
+    if (t) return t;
+  }
+  // Out of turns — repeat the last one so the agent loop doesn't spin.
+  return fixture.turns[fixture.turns.length - 1] ?? { text: "" };
+}
+
+function chunkText(text: string, size: number): string[] {
+  if (size <= 0 || text.length === 0) return text ? [text] : [];
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += size) out.push(text.slice(i, i + size));
+  return out;
+}
+
+function buildFinalMessage(
+  text: string,
+  toolCalls?: FakeTurn["toolCalls"],
+): Message {
+  const content: Array<Record<string, unknown>> = [];
+  if (text) content.push({ type: "text", text, citations: null });
+  if (toolCalls) {
+    for (const tc of toolCalls) {
+      content.push({
+        type: "tool_use",
+        id: tc.id ?? `toolu_${Math.random().toString(36).slice(2, 14)}`,
+        name: tc.name,
+        input: tc.input,
+      });
+    }
+  }
+  return {
+    id: `msg_${Math.random().toString(36).slice(2, 14)}`,
+    type: "message",
+    role: "assistant",
+    model: "botholomew-fake-llm",
+    content,
+    stop_reason: toolCalls?.length ? "tool_use" : "end_turn",
+    stop_sequence: null,
+    usage: {
+      input_tokens: 100,
+      output_tokens: Math.max(1, Math.floor(text.length / 4)),
+      cache_creation_input_tokens: 0,
+      cache_read_input_tokens: 0,
+      service_tier: "standard",
+      server_tool_use: null,
+    },
+  } as unknown as Message;
+}
+
+class FakeMessageStream extends EventEmitter {
+  private resolveFinal: (m: Message) => void = () => {};
+  private readonly finalPromise: Promise<Message>;
+
+  constructor(private readonly turn: FakeTurn) {
+    super();
+    this.finalPromise = new Promise<Message>((resolve) => {
+      this.resolveFinal = resolve;
+    });
+    queueMicrotask(() => this.run());
+  }
+
+  private async run(): Promise<void> {
+    const text = this.turn.text ?? this.turn.chunks?.join("") ?? "";
+    const chunks =
+      this.turn.chunks ?? chunkText(text, this.turn.chunkSize ?? 6);
+    const delay = this.turn.delayMs ?? 40;
+    for (const chunk of chunks) {
+      this.emit("text", chunk);
+      if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+    }
+    const final = buildFinalMessage(text, this.turn.toolCalls);
+    for (const block of final.content) {
+      if ((block as { type: string }).type === "tool_use") {
+        this.emit("contentBlock", block as ToolUseBlock);
+      }
+    }
+    this.resolveFinal(final);
+  }
+
+  finalMessage(): Promise<Message> {
+    return this.finalPromise;
+  }
+}
+
+function extractLastUserText(
+  messages: Array<{ role?: string; content?: unknown }>,
+): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role === "user" && typeof m.content === "string") return m.content;
+  }
+  return "";
+}
+
+function isTitleGeneratorCall(system: unknown): boolean {
+  return typeof system === "string" && /title generator/i.test(system);
+}
+
+export function createFakeAnthropicClient(): Anthropic {
+  return {
+    messages: {
+      stream(params: {
+        system?: unknown;
+        messages: Array<{ role?: string; content?: unknown }>;
+      }) {
+        // Title generation runs in parallel with runChatTurn; don't let it
+        // consume a fixture turn meant for the main conversation.
+        if (isTitleGeneratorCall(params.system)) {
+          return new FakeMessageStream({ text: "Chat session", delayMs: 0 });
+        }
+        const turn = selectTurn(extractLastUserText(params.messages));
+        return new FakeMessageStream(turn);
+      },
+      async create(params: {
+        system?: unknown;
+        messages: Array<{ role?: string; content?: unknown }>;
+      }): Promise<Message> {
+        if (isTitleGeneratorCall(params.system)) {
+          return buildFinalMessage("Chat session");
+        }
+        const turn = selectTurn(extractLastUserText(params.messages));
+        return buildFinalMessage(
+          turn.text ?? turn.chunks?.join("") ?? "",
+          turn.toolCalls,
+        );
+      },
+    },
+  } as unknown as Anthropic;
+}

package/src/daemon/fake-mcp.ts

@@ -0,0 +1,74 @@
+/**
+ * Canned MCP responses for capture mode (BOTHOLOMEW_FAKE_LLM=1). Lets
+ * `mcp_search` and `mcp_exec` return demo-friendly results without requiring
+ * a live MCPX gateway. The shapes mirror what the real tools emit.
+ */
+
+export interface FakeMcpSearchResult {
+  server: string;
+  tool: string;
+  description: string;
+  score: number;
+  match_type: string;
+}
+
+export function isCaptureMode(): boolean {
+  return process.env.BOTHOLOMEW_FAKE_LLM === "1";
+}
+
+export function fakeMcpSearch(query: string): FakeMcpSearchResult[] | null {
+  const q = query.toLowerCase();
+  if (/calendar|schedule|event|meeting/.test(q)) {
+    return [
+      {
+        server: "google-calendar",
+        tool: "ListEvents",
+        description:
+          "List events on a user's Google Calendar within a date range.",
+        score: 0.94,
+        match_type: "semantic",
+      },
+      {
+        server: "google-calendar",
+        tool: "CreateEvent",
+        description: "Create a new event on a user's Google Calendar.",
+        score: 0.78,
+        match_type: "semantic",
+      },
+    ];
+  }
+  if (/email|gmail|mail/.test(q)) {
+    return [
+      {
+        server: "gmail",
+        tool: "SendEmail",
+        description: "Send an email from the user's Gmail account.",
+        score: 0.91,
+        match_type: "semantic",
+      },
+    ];
+  }
+  return null;
+}
+
+export function fakeMcpExec(
+  server: string,
+  tool: string,
+  _args: Record<string, unknown> | undefined,
+): string | null {
+  if (server === "google-calendar" && tool === "ListEvents") {
+    return JSON.stringify(
+      {
+        events: [
+          { start: "09:00", summary: "Sprint planning" },
+          { start: "11:30", summary: "Design review with Pascal" },
+          { start: "14:00", summary: "Focus block: v0.8 roadmap" },
+          { start: "16:30", summary: "1:1 with Sterling" },
+        ],
+      },
+      null,
+      2,
+    );
+  }
+  return null;
+}

package/src/daemon/llm-client.ts

@@ -0,0 +1,12 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { BotholomewConfig } from "../config/schemas.ts";
+import { createFakeAnthropicClient } from "./fake-llm.ts";
+
+export function createLlmClient(config: BotholomewConfig): Anthropic {
+  if (process.env.BOTHOLOMEW_FAKE_LLM === "1") {
+    return createFakeAnthropicClient();
+  }
+  return new Anthropic({
+    apiKey: config.anthropic_api_key || undefined,
+  });
+}

package/src/daemon/llm.ts

@@ -1,4 +1,3 @@
-import Anthropic from "@anthropic-ai/sdk";
 import type {
   Message,
   MessageParam,
@@ -14,6 +13,7 @@ import { registerAllTools } from "../tools/registry.ts";
 import { getTool, type ToolContext, toAnthropicTools } from "../tools/tool.ts";
 import { fitToContextWindow, getMaxInputTokens } from "./context.ts";
 import { clearLargeResults, maybeStoreResult } from "./large-results.ts";
+import { createLlmClient } from "./llm-client.ts";
 
 registerAllTools();
 
@@ -60,9 +60,7 @@ export async function runAgentLoop(input: {
     callbacks,
   } = input;
 
-  const client = new Anthropic({
-    apiKey: config.anthropic_api_key || undefined,
-  });
+  const client = createLlmClient(config);
 
   // Build predecessor context from completed blocking tasks
   let predecessorContext = "";

package/src/db/context.ts

@@ -179,6 +179,19 @@ export async function getContextItemByPath(
   return row ? rowToContextItem(row) : null;
 }
 
+export async function getContextItemBySourcePath(
+  db: DbConnection,
+  sourcePath: string,
+  sourceType: "file" | "url",
+): Promise<ContextItem | null> {
+  const row = await db.queryGet<ContextItemRow>(
+    "SELECT * FROM context_items WHERE source_path = ?1 AND source_type = ?2 LIMIT 1",
+    sourcePath,
+    sourceType,
+  );
+  return row ? rowToContextItem(row) : null;
+}
+
 /**
  * Look up a context item by UUID (if the value looks like one) or by context_path.
  */

package/src/tools/mcp/exec.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { fakeMcpExec, isCaptureMode } from "../../daemon/fake-mcp.ts";
 import { formatCallToolResult } from "../../mcpx/client.ts";
 import type { ToolDefinition } from "../tool.ts";
 
@@ -81,6 +82,17 @@ export const mcpExecTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
+    if (isCaptureMode()) {
+      const canned = fakeMcpExec(input.server, input.tool, input.args);
+      if (canned) {
+        return {
+          result: canned,
+          is_error: false,
+          error_kind: undefined,
+          hint: undefined,
+        };
+      }
+    }
     if (!ctx.mcpxClient) {
       return {
         result:

package/src/tools/mcp/search.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { fakeMcpSearch, isCaptureMode } from "../../daemon/fake-mcp.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
@@ -36,6 +37,16 @@ export const mcpSearchTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
+    if (isCaptureMode()) {
+      const canned = fakeMcpSearch(input.query);
+      if (canned) {
+        return {
+          results: canned,
+          is_error: false,
+          hint: "Use mcp_info with server and tool name to see the full input schema before calling mcp_exec.",
+        };
+      }
+    }
     if (!ctx.mcpxClient) {
       return {
         results: [],

package/src/tui/App.tsx

@@ -209,6 +209,28 @@ export function App({
     return () => clearTimeout(timer);
   }, []);
 
+  // Capture-mode tab auto-cycle. Under VHS/ttyd the Tab key doesn't reliably
+  // reach Ink, so a docs tape can't drive the tab tour by keystroke. When
+  // BOTHOLOMEW_CAPTURE_TAB_CYCLE is set, schedule timers that walk through
+  // every tab so a single recording can show all panels.
+  //
+  // Format: "dwellMs" or "dwellMs:startDelayMs". The optional start delay
+  // lets a tape finish a streamed chat reply before the cycle kicks in.
+  useEffect(() => {
+    const spec = process.env.BOTHOLOMEW_CAPTURE_TAB_CYCLE;
+    if (!spec) return;
+    const [dwellRaw, delayRaw] = spec.split(":");
+    const dwellMs = Number.parseInt(dwellRaw ?? "", 10) || 2500;
+    const startDelayMs = Number.parseInt(delayRaw ?? "", 10) || 0;
+    const sequence: TabId[] = [2, 3, 4, 5, 6, 7, 1];
+    const timers = sequence.map((tab, i) =>
+      setTimeout(() => setActiveTab(tab), startDelayMs + dwellMs * (i + 1)),
+    );
+    return () => {
+      for (const t of timers) clearTimeout(t);
+    };
+  }, []);
+
   // Stable ref for App-level input handler — same pattern as InputBar to
   // prevent Ink's useInput from re-registering stdin listeners on every render.
   const activeTabRef = useRef(activeTab);

package/src/utils/title.ts

@@ -1,5 +1,5 @@
-import Anthropic from "@anthropic-ai/sdk";
 import type { BotholomewConfig } from "../config/schemas.ts";
+import { createLlmClient } from "../daemon/llm-client.ts";
 import { withDb } from "../db/connection.ts";
 import { updateThreadTitle } from "../db/threads.ts";
 import { logger } from "./logger.ts";
@@ -17,9 +17,7 @@ export async function generateThreadTitle(
   context: string,
 ): Promise<void> {
   try {
-    const client = new Anthropic({
-      apiKey: config.anthropic_api_key || undefined,
-    });
+    const client = createLlmClient(config);
 
     const response = await client.messages.create({
       model: config.chunker_model,