botholomew

library0.21.1jsnpmunverified

Botholomew is an autonomous AI agent for knowledge work that runs in the background, processing tasks from a queue. It reads email, summarizes documents, researches topics, organizes notes, and maintains context over time. Version 0.21.1 is the current stable release, with regular updates on GitHub. Key differentiators: no shell or filesystem access (uses a per-project knowledge store managed by membot with logical paths), autonomous workers with task claiming via O_EXCL lockfiles, portable project-as-filesystem approach, and safe by default with sandboxed file access and MCP-injected external capabilities.

ai-ml productivity

npm install botholomew

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BOTHOLOMEW

botholomew

ai-mljavascriptv0.21.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

botholomew

✓ import botholomew from 'botholomew'

✗ const botholomew = require('botholomew')

ESM-only package; no CommonJS support.

Demonstrates initializing a Botholomew agent, adding a task, running a worker, and sending a chat message.

import botholomew from 'botholomew'; // Initialize with a project directory const agent = botholomew.create({ project: './my-project', apiKey: process.env.ANTHROPIC_API_KEY ?? '' }); // Add a task to the queue await agent.addTask({ description: 'Summarize the latest quarterly report', priority: 'high' }); // Run a single worker cycle await agent.worker.run(); // Or start a persistent background worker // agent.worker.startPersist(); // Chat with the agent const response = await agent.chat.send('What are my top priorities today?'); console.log(response);

Debug

Known issues

breakingBotholomew has no shell and no filesystem access. The knowledge store is keyed by logical_path, not real paths. Attempts to access ~/.ssh/id_rsa will fail silently.

fix

Use membot add to bring in local files. All external capabilities require explicit MCP server configuration.

affects: >=0.0.0

gotchaThe project directory is a real filesystem location where tasks/, schedules/, prompts/, skills/ folders are created and managed. These files are readable/writable by the agent only through a sandbox helper that rejects symlinks.

fix

Ensure the project directory is writable and contains the expected subfolders. Do not symlink inside these folders.

affects: >=0.0.0

gotchaTasks and schedules are claimed via O_EXCL lockfiles. If a worker crashes, the lockfile may remain, blocking other workers. Automatic reaping runs periodically.

fix

Manually remove stale lockfiles from the tasks/ or schedules/ directory if reaping does not work.

affects: >=0.0.0

breakingMCP servers are required for any external tool usage (email, Slack, web). Without MCP servers configured, the agent only has internal knowledge store access.

fix

Set up MCP servers via MCPX (https://github.com/evantahler/mcpx). Use a gateway like Arcade.dev for pre-authenticated services.

affects: >=0.0.0

deprecatedThe botholomew CLI subcommand 'botholomew worker run --persist' has been deprecated in favor of 'botholomew worker start' which provides better logging and health checks.

fix

Use 'botholomew worker start' instead.

affects: >=0.21.0

Errors

Common errors & fixes

Error: Cannot find module 'mcpx'

MCPX package is required for external connectivity but not installed.

fix

Install mcpx: npm install mcpx or add it to your project dependencies.

TypeError: botholomew.create is not a function

Using default import incorrectly or using require() on an ESM-only package.

fix

Use import botholomew from 'botholomew' (ESM) instead of require.

Error: Project must contain a tasks/ directory

Initializing a new project without running botholomew init first.

fix

Run 'botholomew init' in your project directory to create the required structure.

Upgrade

Version history

0.21.1latest on npm

Audit

Dependencies

membotrequiredManages the knowledge store (DuckDB) for reading, writing, searching, and deleting project data.

mcpxoptionalWires up MCP servers for external capabilities like email, Slack, and web.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/evantahler/botholomew ↗

packagebotholomew ↗

homepagehttps://github.com/evantahler/botholomew#readme ↗