Botholomew

Autonomous

Background workers claim tasks, work them with Claude, and log every interaction. Spawn one-shot workers, a long-running --persist worker, or point cron at `botholomew worker run`.

Portable

Each project is a `.botholomew/` directory — markdown plus DuckDB. Copy it, share it, check it in, or .gitignore it.

Your data, your disk

Tasks, threads, ingested context, and embeddings live locally in DuckDB with BM25 keyword search and `array_cosine_distance` vector search. Model calls go direct to Anthropic and OpenAI.

Extensible

External tools come from MCP servers via MCPX — run them locally (Gmail, Slack, GitHub) or connect through a gateway like Arcade.dev to reach hundreds of authenticated services.

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 an 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.

Self-modifying

The agent maintains its own `beliefs.md` and `goals.md` — it learns, updates its priors, and revises its goals as it works. It can also author its own slash-command skills mid-conversation.

Why Botholomew?

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.

Quickstart

bash

# 1. Install (requires Bun 1.1+)
bun install -g botholomew

# 2. Initialize a project
botholomew init

# 3. Set your Anthropic API key (embeddings run locally — no other key needed)
export ANTHROPIC_API_KEY=sk-ant-...

# 4. Queue some work and run a worker
botholomew task add "Summarize every markdown file in ~/notes"
botholomew worker run

# 5. Or chat with the agent interactively
botholomew chat

See Get started for the full walkthrough, then dive into Architecture to understand the moving parts.

For LLMs and AI agents

This site is published in LLM-friendly formats too:

/llms.txt — table of contents with links to every documentation page
/llms-full.txt — the entire doc set bundled into one file
Append .md to any page URL (e.g. /architecture.md) to get the raw markdown source

Point your agent at one of these instead of scraping HTML.

BotholomewAn AI agent for knowledge work.