botholomew 0.8.2 → 0.8.4

package/README.md

@@ -8,15 +8,17 @@
 
 ![Botholomew chat TUI](docs/assets/chat-happy-path.gif)
 
-**A local AI agent for knowledge work.** Botholomew is an autonomous agent
+**An AI agent for knowledge work.** Botholomew is an autonomous agent
 that works its way through a task queue — reading email, summarizing
 documents, researching topics, organizing notes, and maintaining context
 over time — while you sleep, work, or chat with it.
 
-Unlike coding agents, Botholomew has **no shell, no filesystem, and no network
-tools** by default. Everything it touches lives inside a single DuckDB database
-at `.botholomew/data.duckdb` and a handful of markdown files. External access
-is granted deliberately, per project, through MCP servers.
+Unlike coding agents, Botholomew has **no shell and no direct access to
+your filesystem**. It can't edit files on disk — instead, it ingests local
+files, folders, and URLs into a DuckDB-backed context store that it can
+read, search, and summarize. External capabilities (email, Slack, the web,
+and hundreds of other services) are granted deliberately, per project,
+through MCP servers wired up via [MCPX](https://github.com/evantahler/mcpx).
 
 ---
 
@@ -27,19 +29,19 @@ is granted deliberately, per project, through MCP servers.
   long-running `--persist` worker, or point cron at `botholomew worker run`.
 - **Portable.** Each project is a `.botholomew/` directory — markdown +
   DuckDB. Copy it, share it, check it in (or `.gitignore` it).
-- **Local.** All data stays on your machine. Embeddings are indexed in
-  DuckDB's native vector store with HNSW. Model calls go direct to Anthropic
-  and OpenAI.
+- **Your data, your disk.** Project state — tasks, threads, ingested
+  context, embeddings — lives in `.botholomew/`, indexed in DuckDB with
+  HNSW for vector search. Model calls go direct to Anthropic and OpenAI;
+  any further reach is scoped to the MCP servers you add.
 - **Extensible.** External tools come from MCP servers via
   [MCPX](https://github.com/evantahler/mcpx) — run them locally (Gmail,
   Slack, GitHub) or connect through an MCP gateway like
   [Arcade.dev](https://www.arcade.dev/) to reach hundreds of
   authenticated services without managing each server yourself.
   Reusable workflows are defined as markdown "skills" (slash commands).
-- **Safe by default.** The agent has no shell, no network, and no
-  filesystem access of its own. Everything it can touch lives in
-  `.botholomew/` — and every external capability is something you
-  explicitly add.
+- **Safe by default.** The agent has no shell and no direct filesystem
+  access. Out of the box, everything it can touch lives in `.botholomew/`;
+  every external capability is a MCP server you explicitly add.
 - **Concurrent.** Many workers can run at once. Each registers itself in
   the DB and heartbeats; crashed workers get reaped and their tasks go
   back into the queue automatically.
@@ -49,6 +51,15 @@ is granted deliberately, per project, through MCP servers.
 
 ---
 
+## Demo
+
+A full tour of the chat TUI — every tab, slash-command autocomplete,
+the message queue, tool-call visualization, and the live workers panel:
+
+![Tour of every tab in the chat TUI](docs/assets/full-tour.gif)
+
+---
+
 ## Install
 
 Requires [Bun](https://bun.sh) 1.1+.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "botholomew",
-  "version": "0.8.2",
-  "description": "Local, autonomous AI agent for knowledge work — works your task queue while you sleep.",
+  "version": "0.8.4",
+  "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {
     "botholomew": "./src/cli.ts"

package/src/config/loader.ts

@@ -1,4 +1,5 @@
 import { getConfigPath } from "../constants.ts";
+import { setLogLevel } from "../utils/logger.ts";
 import { type BotholomewConfig, DEFAULT_CONFIG } from "./schemas.ts";
 
 export async function loadConfig(
@@ -22,6 +23,8 @@ export async function loadConfig(
     config.openai_api_key = process.env.OPENAI_API_KEY;
   }
 
+  setLogLevel(config.log_level);
+
   return config;
 }
 

package/src/config/schemas.ts

@@ -15,6 +15,7 @@ export interface BotholomewConfig {
   worker_stopped_retention_seconds?: number;
   schedule_min_interval_seconds?: number;
   schedule_claim_stale_seconds?: number;
+  log_level?: string;
 }
 
 export const DEFAULT_CONFIG: Required<BotholomewConfig> = {
@@ -34,4 +35,5 @@ export const DEFAULT_CONFIG: Required<BotholomewConfig> = {
   worker_stopped_retention_seconds: 3600,
   schedule_min_interval_seconds: 60,
   schedule_claim_stale_seconds: 300,
+  log_level: "",
 };

package/src/context/embedder-impl.ts

@@ -0,0 +1,69 @@
+import type { BotholomewConfig } from "../config/schemas.ts";
+
+type EmbedFn = (
+  texts: string[],
+  config: Required<BotholomewConfig>,
+) => Promise<number[][]>;
+
+interface OpenAIEmbeddingResponse {
+  data: { embedding: number[]; index: number }[];
+  usage: { total_tokens: number };
+}
+
+/**
+ * Embed multiple texts using the OpenAI embeddings API.
+ * Returns an array of float vectors with the configured dimension.
+ */
+export async function embed(
+  texts: string[],
+  config: Required<BotholomewConfig>,
+): Promise<number[][]> {
+  if (texts.length === 0) return [];
+
+  if (!config.openai_api_key) {
+    throw new Error(
+      "OpenAI API key is required for embeddings. Set openai_api_key in config or OPENAI_API_KEY env var.",
+    );
+  }
+
+  const response = await fetch("https://api.openai.com/v1/embeddings", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.openai_api_key}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      input: texts,
+      model: config.embedding_model,
+      dimensions: config.embedding_dimension,
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      `OpenAI embeddings API error (${response.status}): ${body}`,
+    );
+  }
+
+  const result = (await response.json()) as OpenAIEmbeddingResponse;
+
+  // Sort by index to ensure order matches input
+  const sorted = result.data.sort((a, b) => a.index - b.index);
+  return sorted.map((d) => d.embedding);
+}
+
+/**
+ * Embed a single text string.
+ */
+export async function embedSingle(
+  text: string,
+  config: Required<BotholomewConfig>,
+): Promise<number[]> {
+  const results = await embed([text], config);
+  const vec = results[0];
+  if (!vec) throw new Error("embed returned empty results");
+  return vec;
+}
+
+export type { EmbedFn };

package/src/context/embedder.ts

@@ -1,69 +1,9 @@
-import type { BotholomewConfig } from "../config/schemas.ts";
-
-type EmbedFn = (
-  texts: string[],
-  config: Required<BotholomewConfig>,
-) => Promise<number[][]>;
-
-interface OpenAIEmbeddingResponse {
-  data: { embedding: number[]; index: number }[];
-  usage: { total_tokens: number };
-}
-
-/**
- * Embed multiple texts using the OpenAI embeddings API.
- * Returns an array of float vectors with the configured dimension.
- */
-export async function embed(
-  texts: string[],
-  config: Required<BotholomewConfig>,
-): Promise<number[][]> {
-  if (texts.length === 0) return [];
-
-  if (!config.openai_api_key) {
-    throw new Error(
-      "OpenAI API key is required for embeddings. Set openai_api_key in config or OPENAI_API_KEY env var.",
-    );
-  }
-
-  const response = await fetch("https://api.openai.com/v1/embeddings", {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${config.openai_api_key}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({
-      input: texts,
-      model: config.embedding_model,
-      dimensions: config.embedding_dimension,
-    }),
-  });
-
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(
-      `OpenAI embeddings API error (${response.status}): ${body}`,
-    );
-  }
-
-  const result = (await response.json()) as OpenAIEmbeddingResponse;
-
-  // Sort by index to ensure order matches input
-  const sorted = result.data.sort((a, b) => a.index - b.index);
-  return sorted.map((d) => d.embedding);
-}
-
-/**
- * Embed a single text string.
- */
-export async function embedSingle(
-  text: string,
-  config: Required<BotholomewConfig>,
-): Promise<number[]> {
-  const results = await embed([text], config);
-  const vec = results[0];
-  if (!vec) throw new Error("embed returned empty results");
-  return vec;
-}
-
-export type { EmbedFn };
+// Re-exports the real embedder implementation from `embedder-impl.ts`.
+//
+// Why the indirection: tests that touch code importing from this file (e.g.,
+// `src/chat/agent.ts`, `src/worker/prompt.ts`) use Bun's `mock.module()` to
+// stub the embedder so they don't hit OpenAI. Bun's module mocks are
+// process-wide and can leak into subsequent test files. By keeping the real
+// implementation in `embedder-impl.ts`, `test/context/embedder.test.ts` can
+// import the real embedder from a path that nothing mocks.
+export * from "./embedder-impl.ts";

package/src/tools/context/refresh.ts

@@ -59,7 +59,7 @@ const empty = {
 export const contextRefreshTool = {
   name: "context_refresh",
   description:
-    "Re-read source files from disk / re-fetch source URLs, update stored content if it changed, and re-embed only changed items. Use `path` for a single item or subtree, or `all: true` for every sourced item. Items without a source_path are skipped. URL fetches use the project's MCPX client when available and fall back to plain HTTP.",
+    "[[ bash equivalent command: curl ]] Re-read source files from disk / re-fetch source URLs, update stored content if it changed, and re-embed only changed items. Use `path` for a single item or subtree, or `all: true` for every sourced item. Items without a source_path are skipped. URL fetches use the project's MCPX client when available and fall back to plain HTTP.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/context/search.ts

@@ -24,7 +24,8 @@ const outputSchema = z.object({
 
 export const contextSearchTool = {
   name: "context_search",
-  description: "Search context by keyword.",
+  description:
+    "[[ bash equivalent command: grep -r ]] Search context by keyword.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/create.ts

@@ -18,7 +18,8 @@ const outputSchema = z.object({
 
 export const contextCreateDirTool = {
   name: "context_create_dir",
-  description: "Create a directory in context.",
+  description:
+    "[[ bash equivalent command: mkdir -p ]] Create a directory in context.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/list.ts

@@ -38,7 +38,8 @@ const outputSchema = z.object({
 
 export const contextListDirTool = {
   name: "context_list_dir",
-  description: "List directory contents in context.",
+  description:
+    "[[ bash equivalent command: ls ]] List directory contents in context.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/size.ts

@@ -26,7 +26,8 @@ const outputSchema = z.object({
 
 export const contextDirSizeTool = {
   name: "context_dir_size",
-  description: "Get the total size of context items in a directory.",
+  description:
+    "[[ bash equivalent command: du -s ]] Get the total size of context items in a directory.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/tree.ts

@@ -66,7 +66,7 @@ type TreeEntry = DirNode | FileNode;
 export const contextTreeTool = {
   name: "context_tree",
   description:
-    "Explore your context filesystem with a bird's-eye view — shows many paths across nested directories in one call. Reach for this first when you need to discover what content exists before reading a specific file (context_read) or running a keyword search (context_search). Returns a markdown-style tree; tune max_depth and items_per_dir to bound output, or pass a deeper path to drill into a subtree.",
+    "[[ bash equivalent command: tree ]] Explore your context filesystem with a bird's-eye view — shows many paths across nested directories in one call. Reach for this first when you need to discover what content exists before reading a specific file (context_read) or running a keyword search (context_search). Returns a markdown-style tree; tune max_depth and items_per_dir to bound output, or pass a deeper path to drill into a subtree.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/copy.ts

@@ -20,7 +20,7 @@ const outputSchema = z.object({
 
 export const contextCopyTool = {
   name: "context_copy",
-  description: "Copy a context item.",
+  description: "[[ bash equivalent command: cp ]] Copy a context item.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/count-lines.ts

@@ -13,7 +13,8 @@ const outputSchema = z.object({
 
 export const contextCountLinesTool = {
   name: "context_count_lines",
-  description: "Count the number of lines in a text context item.",
+  description:
+    "[[ bash equivalent command: wc -l ]] Count the number of lines in a text context item.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/delete.ts

@@ -24,7 +24,8 @@ const outputSchema = z.object({
 
 export const contextDeleteTool = {
   name: "context_delete",
-  description: "Delete a context item or directory.",
+  description:
+    "[[ bash equivalent command: rm -r ]] Delete a context item or directory.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/edit.ts

@@ -27,7 +27,7 @@ const outputSchema = z.object({
 export const contextEditTool = {
   name: "context_edit",
   description:
-    "Apply git-style patches to a context item. Each patch specifies a line range to replace.",
+    "[[ bash equivalent command: patch ]] Apply git-style patches to a context item. Each patch specifies a line range to replace.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/exists.ts

@@ -13,7 +13,8 @@ const outputSchema = z.object({
 
 export const contextExistsTool = {
   name: "context_exists",
-  description: "Check if a context item exists.",
+  description:
+    "[[ bash equivalent command: test -e ]] Check if a context item exists.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/info.ts

@@ -25,7 +25,7 @@ const outputSchema = z.object({
 export const contextInfoTool = {
   name: "context_info",
   description:
-    "Show context item metadata (size, MIME type, line count, etc.).",
+    "[[ bash equivalent command: stat ]] Show context item metadata: size, MIME type, line count, etc.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/move.ts

@@ -19,7 +19,8 @@ const outputSchema = z.object({
 
 export const contextMoveTool = {
   name: "context_move",
-  description: "Move or rename a context item.",
+  description:
+    "[[ bash equivalent command: mv ]] Move or rename a context item.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/read.ts

@@ -18,7 +18,8 @@ const outputSchema = z.object({
 
 export const contextReadTool = {
   name: "context_read",
-  description: "Read a context item's contents.",
+  description:
+    "[[ bash equivalent command: cat ]] Read a context item's contents.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/write.ts

@@ -54,7 +54,7 @@ const outputSchema = z.object({
 export const contextWriteTool = {
   name: "context_write",
   description:
-    "Write content to a context item. By default, fails if the path already exists — pass on_conflict='overwrite' to replace.",
+    "[[ bash equivalent command: tee ]] Write content to a context item. By default, fails if the path already exists — pass on_conflict='overwrite' to replace.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/utils/logger.ts

@@ -4,34 +4,78 @@ function ts(): string {
   return ansis.gray(new Date().toTimeString().slice(0, 8));
 }
 
+const LEVELS = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+} as const;
+
+type LogLevel = keyof typeof LEVELS;
+
+function parseLevel(raw: string | undefined): number | undefined {
+  const key = raw?.toLowerCase();
+  if (key && key in LEVELS) return LEVELS[key as LogLevel];
+  return undefined;
+}
+
+const envPinned = parseLevel(process.env.BOTHOLOMEW_LOG_LEVEL) !== undefined;
+
+function defaultLevel(): number {
+  const explicit = parseLevel(process.env.BOTHOLOMEW_LOG_LEVEL);
+  if (explicit !== undefined) return explicit;
+  if (process.env.NODE_ENV === "test") return LEVELS.error;
+  return LEVELS.info;
+}
+
+let currentLevel = defaultLevel();
+
+/**
+ * Apply a log level from config. `BOTHOLOMEW_LOG_LEVEL` always wins, so
+ * this is a no-op when that env var is set. Empty/invalid values are
+ * ignored — callers can pass `config.log_level` directly without checking.
+ */
+export function setLogLevel(level: string | undefined): void {
+  if (envPinned) return;
+  const parsed = parseLevel(level);
+  if (parsed === undefined) return;
+  currentLevel = parsed;
+}
+
 export const logger = {
   info(msg: string) {
+    if (currentLevel < LEVELS.info) return;
     console.log(ts(), ansis.blue("ℹ"), msg);
   },
 
   success(msg: string) {
+    if (currentLevel < LEVELS.info) return;
     console.log(ts(), ansis.green("✓"), msg);
   },
 
   warn(msg: string) {
+    if (currentLevel < LEVELS.warn) return;
     console.log(ts(), ansis.yellow("⚠"), msg);
   },
 
   error(msg: string) {
+    if (currentLevel < LEVELS.error) return;
     console.error(ts(), ansis.red("✗"), msg);
   },
 
   debug(msg: string) {
-    if (process.env.BOTHOLOMEW_DEBUG) {
-      console.log(ts(), ansis.gray("·"), ansis.gray(msg));
-    }
+    if (currentLevel < LEVELS.debug) return;
+    console.log(ts(), ansis.gray("·"), ansis.gray(msg));
   },
 
   dim(msg: string) {
+    if (currentLevel < LEVELS.info) return;
     console.log(ts(), ansis.dim(msg));
   },
 
   phase(name: string, detail?: string) {
+    if (currentLevel < LEVELS.info) return;
     const tag = ansis.magenta.bold(`[[${name}]]`);
     if (detail) {
       console.log(ts(), tag, ansis.dim(detail));