botholomew 0.7.10 → 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.10",
+  "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/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/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,