botholomew 0.8.3 → 0.8.5

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.3",
-  "description": "Local, autonomous AI agent for knowledge work — works your task queue while you sleep.",
+  "version": "0.8.5",
+  "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/tools/context/refresh.ts

@@ -6,6 +6,7 @@ import {
   listContextItemsByPrefix,
   resolveContextItem,
 } from "../../db/context.ts";
+import { buildContextTree } from "../dir/tree.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
@@ -43,6 +44,12 @@ const outputSchema = z.object({
   ),
   message: z.string(),
   is_error: z.boolean(),
+  tree: z
+    .string()
+    .optional()
+    .describe(
+      "Snapshot of the context filesystem after the refresh so you can see what's currently stored.",
+    ),
 });
 
 const empty = {
@@ -54,6 +61,7 @@ const empty = {
   chunks: 0,
   embeddings_skipped: false,
   items: [],
+  tree: undefined as string | undefined,
 };
 
 export const contextRefreshTool = {
@@ -127,10 +135,13 @@ export const contextRefreshTool = {
       parts.push("embeddings skipped (no OpenAI API key configured)");
     }
 
+    const { tree } = await buildContextTree(ctx.conn);
+
     return {
       ...result,
       message: parts.join(", "),
       is_error: false,
+      tree,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/dir/tree.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { DbConnection } from "../../db/connection.ts";
 import {
   countContextItemsByPrefix,
   listContextItemsByPrefix,
@@ -9,6 +10,185 @@ const DEFAULT_MAX_DEPTH = 3;
 const DEFAULT_ITEMS_PER_DIR = 15;
 const HARD_FETCH_CAP = 1000;
 
+export interface BuildContextTreeOptions {
+  path?: string;
+  maxDepth?: number;
+  itemsPerDir?: number;
+}
+
+export interface BuildContextTreeResult {
+  tree: string;
+  total_items: number;
+  truncated_dirs: Array<{ path: string; shown: number; total: number }>;
+  hint: string;
+}
+
+interface DirNode {
+  name: string;
+  fullPath: string;
+  isDir: true;
+  children: TreeEntry[];
+}
+
+interface FileNode {
+  name: string;
+  fullPath: string;
+  isDir: false;
+}
+
+type TreeEntry = DirNode | FileNode;
+
+export async function buildContextTree(
+  conn: DbConnection,
+  options: BuildContextTreeOptions = {},
+): Promise<BuildContextTreeResult> {
+  const path = options.path ?? "/";
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const itemsPerDir = options.itemsPerDir ?? DEFAULT_ITEMS_PER_DIR;
+  const normalizedPath = path.endsWith("/") ? path : `${path}/`;
+
+  const totalItems = await countContextItemsByPrefix(conn, path, {
+    recursive: true,
+  });
+
+  if (totalItems === 0) {
+    return {
+      tree: `${path}\n  (empty)`,
+      total_items: 0,
+      truncated_dirs: [],
+      hint: "Directory is empty.",
+    };
+  }
+
+  const items = await listContextItemsByPrefix(conn, path, {
+    recursive: true,
+    limit: HARD_FETCH_CAP,
+  });
+
+  // Build tree structure: dirs map child name -> child node
+  const root: DirNode = {
+    name: path,
+    fullPath: path,
+    isDir: true,
+    children: [],
+  };
+  const dirIndex = new Map<string, DirNode>();
+  dirIndex.set(stripTrailingSlash(path), root);
+
+  for (const item of items) {
+    const relative = item.context_path.slice(normalizedPath.length);
+    if (relative.length === 0) continue; // root itself, skip
+    const parts = relative.split("/").filter((p) => p.length > 0);
+    const isExplicitDir = item.mime_type === "inode/directory";
+
+    // Walk segments, creating intermediate directories as needed
+    let parentDir = root;
+    let currentRel = "";
+    for (let i = 0; i < parts.length; i++) {
+      const segment = parts[i];
+      if (!segment) continue;
+      currentRel = currentRel ? `${currentRel}/${segment}` : segment;
+      const fullPath = `${normalizedPath}${currentRel}`;
+      const isLeaf = i === parts.length - 1;
+      const isDirHere = !isLeaf || isExplicitDir;
+
+      if (isDirHere) {
+        const key = stripTrailingSlash(fullPath);
+        let dir = dirIndex.get(key);
+        if (!dir) {
+          dir = {
+            name: segment,
+            fullPath,
+            isDir: true,
+            children: [],
+          };
+          dirIndex.set(key, dir);
+          parentDir.children.push(dir);
+        }
+        parentDir = dir;
+      } else {
+        parentDir.children.push({
+          name: segment,
+          fullPath,
+          isDir: false,
+        });
+      }
+    }
+  }
+
+  // Sort each directory's children: dirs first, then alphabetical
+  for (const dir of dirIndex.values()) {
+    dir.children.sort((a, b) => {
+      if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+  }
+
+  const truncatedDirs: Array<{
+    path: string;
+    shown: number;
+    total: number;
+  }> = [];
+  const depthLimitedDirs: string[] = [];
+
+  const lines: string[] = [path];
+
+  const render = (dir: DirNode, indent: string, currentDepth: number): void => {
+    const children = dir.children;
+    const total = children.length;
+    const shown = Math.min(total, itemsPerDir);
+    const visible = children.slice(0, shown);
+    const overflow = total - shown;
+
+    if (overflow > 0) {
+      truncatedDirs.push({
+        path: stripTrailingSlash(dir.fullPath),
+        shown,
+        total,
+      });
+    }
+
+    for (let i = 0; i < visible.length; i++) {
+      const child = visible[i];
+      if (!child) continue;
+      const isLastVisible = i === visible.length - 1 && overflow === 0;
+      const connector = isLastVisible ? "└── " : "├── ";
+      const childIndent = isLastVisible ? "    " : "│   ";
+
+      if (child.isDir) {
+        const atDepthLimit = currentDepth + 1 >= maxDepth;
+        if (atDepthLimit && child.children.length > 0) {
+          depthLimitedDirs.push(stripTrailingSlash(child.fullPath));
+          const subCount = countDescendants(child);
+          lines.push(
+            `${indent}${connector}${child.name}/ (${subCount} ${
+              subCount === 1 ? "item" : "items"
+            }, drill in)`,
+          );
+        } else {
+          lines.push(`${indent}${connector}${child.name}/`);
+          render(child, indent + childIndent, currentDepth + 1);
+        }
+      } else {
+        lines.push(`${indent}${connector}${child.name}`);
+      }
+    }
+
+    if (overflow > 0) {
+      lines.push(`${indent}└── ... (+${overflow} more)`);
+    }
+  };
+
+  render(root, "", 0);
+
+  return {
+    tree: lines.join("\n"),
+    total_items: totalItems,
+    truncated_dirs: truncatedDirs,
+    hint: buildHint({ truncatedDirs, depthLimitedDirs, totalItems }),
+  };
+}
+
 const inputSchema = z.object({
   path: z
     .string()
@@ -48,21 +228,6 @@ const outputSchema = z.object({
   hint: z.string(),
 });
 
-interface DirNode {
-  name: string;
-  fullPath: string;
-  isDir: true;
-  children: TreeEntry[];
-}
-
-interface FileNode {
-  name: string;
-  fullPath: string;
-  isDir: false;
-}
-
-type TreeEntry = DirNode | FileNode;
-
 export const contextTreeTool = {
   name: "context_tree",
   description:
@@ -71,163 +236,12 @@ export const contextTreeTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const path = input.path ?? "/";
-    const maxDepth = input.max_depth ?? DEFAULT_MAX_DEPTH;
-    const itemsPerDir = input.items_per_dir ?? DEFAULT_ITEMS_PER_DIR;
-    const normalizedPath = path.endsWith("/") ? path : `${path}/`;
-
-    const totalItems = await countContextItemsByPrefix(ctx.conn, path, {
-      recursive: true,
-    });
-
-    if (totalItems === 0) {
-      return {
-        tree: `${path}\n  (empty)`,
-        is_error: false,
-        total_items: 0,
-        truncated_dirs: [],
-        hint: "Directory is empty.",
-      };
-    }
-
-    const items = await listContextItemsByPrefix(ctx.conn, path, {
-      recursive: true,
-      limit: HARD_FETCH_CAP,
-    });
-
-    // Build tree structure: dirs map child name -> child node
-    const root: DirNode = {
-      name: path,
-      fullPath: path,
-      isDir: true,
-      children: [],
-    };
-    const dirIndex = new Map<string, DirNode>();
-    dirIndex.set(stripTrailingSlash(path), root);
-
-    for (const item of items) {
-      const relative = item.context_path.slice(normalizedPath.length);
-      if (relative.length === 0) continue; // root itself, skip
-      const parts = relative.split("/").filter((p) => p.length > 0);
-      const isExplicitDir = item.mime_type === "inode/directory";
-
-      // Walk segments, creating intermediate directories as needed
-      let parentDir = root;
-      let currentRel = "";
-      for (let i = 0; i < parts.length; i++) {
-        const segment = parts[i];
-        if (!segment) continue;
-        currentRel = currentRel ? `${currentRel}/${segment}` : segment;
-        const fullPath = `${normalizedPath}${currentRel}`;
-        const isLeaf = i === parts.length - 1;
-        const isDirHere = !isLeaf || isExplicitDir;
-
-        if (isDirHere) {
-          const key = stripTrailingSlash(fullPath);
-          let dir = dirIndex.get(key);
-          if (!dir) {
-            dir = {
-              name: segment,
-              fullPath,
-              isDir: true,
-              children: [],
-            };
-            dirIndex.set(key, dir);
-            parentDir.children.push(dir);
-          }
-          parentDir = dir;
-        } else {
-          parentDir.children.push({
-            name: segment,
-            fullPath,
-            isDir: false,
-          });
-        }
-      }
-    }
-
-    // Sort each directory's children: dirs first, then alphabetical
-    for (const dir of dirIndex.values()) {
-      dir.children.sort((a, b) => {
-        if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
-        return a.name.localeCompare(b.name);
-      });
-    }
-
-    const truncatedDirs: Array<{
-      path: string;
-      shown: number;
-      total: number;
-    }> = [];
-    const depthLimitedDirs: string[] = [];
-
-    const lines: string[] = [path];
-
-    const render = (
-      dir: DirNode,
-      indent: string,
-      currentDepth: number,
-    ): void => {
-      const children = dir.children;
-      const total = children.length;
-      const shown = Math.min(total, itemsPerDir);
-      const visible = children.slice(0, shown);
-      const overflow = total - shown;
-
-      if (overflow > 0) {
-        truncatedDirs.push({
-          path: stripTrailingSlash(dir.fullPath),
-          shown,
-          total,
-        });
-      }
-
-      for (let i = 0; i < visible.length; i++) {
-        const child = visible[i];
-        if (!child) continue;
-        const isLastVisible = i === visible.length - 1 && overflow === 0;
-        const connector = isLastVisible ? "└── " : "├── ";
-        const childIndent = isLastVisible ? "    " : "│   ";
-
-        if (child.isDir) {
-          const atDepthLimit = currentDepth + 1 >= maxDepth;
-          if (atDepthLimit && child.children.length > 0) {
-            depthLimitedDirs.push(stripTrailingSlash(child.fullPath));
-            const subCount = countDescendants(child);
-            lines.push(
-              `${indent}${connector}${child.name}/ (${subCount} ${
-                subCount === 1 ? "item" : "items"
-              }, drill in)`,
-            );
-          } else {
-            lines.push(`${indent}${connector}${child.name}/`);
-            render(child, indent + childIndent, currentDepth + 1);
-          }
-        } else {
-          lines.push(`${indent}${connector}${child.name}`);
-        }
-      }
-
-      if (overflow > 0) {
-        lines.push(`${indent}└── ... (+${overflow} more)`);
-      }
-    };
-
-    render(root, "", 0);
-
-    const hint = buildHint({
-      truncatedDirs,
-      depthLimitedDirs,
-      totalItems,
+    const result = await buildContextTree(ctx.conn, {
+      path: input.path,
+      maxDepth: input.max_depth,
+      itemsPerDir: input.items_per_dir,
     });
-
-    return {
-      tree: lines.join("\n"),
-      is_error: false,
-      total_items: totalItems,
-      truncated_dirs: truncatedDirs,
-      hint,
-    };
+    return { ...result, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;
 

package/src/tools/file/write.ts

@@ -6,6 +6,7 @@ import {
   PathConflictError,
   upsertContextItem,
 } from "../../db/context.ts";
+import { buildContextTree } from "../dir/tree.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 function mimeFromPath(path: string): string {
@@ -49,6 +50,12 @@ const outputSchema = z.object({
   error_type: z.string().optional(),
   message: z.string().optional(),
   next_action_hint: z.string().optional(),
+  tree: z
+    .string()
+    .optional()
+    .describe(
+      "Snapshot of the context filesystem after the write so you can see the surrounding files.",
+    ),
 });
 
 export const contextWriteTool = {
@@ -86,7 +93,13 @@ export const contextWriteTool = {
             });
 
       await ingestByPath(ctx.conn, input.path, ctx.config);
-      return { id: item.id, path: item.context_path, is_error: false };
+      const { tree } = await buildContextTree(ctx.conn);
+      return {
+        id: item.id,
+        path: item.context_path,
+        is_error: false,
+        tree,
+      };
     } catch (err) {
       if (err instanceof PathConflictError) {
         return {

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));