Botholomew

 {o,o}
 /)_)
  " "

An AI agent for knowledge work. Point Botholomew at your docs, projects, and inboxes and it reads them, remembers them, and works a durable task queue — summarizing, researching, organizing, chasing things down — while you sleep, work, or chat with it. It runs locally (local LLMs included), and it's built around a large memory store rather than a single chat window.

Botholomew has no shell and no access to your real filesystem. The agent's world is a per-project knowledge store managed by membot — every read, write, search, and delete is addressed by logical_path (a DB key, not a filesystem path), so a prompt-injected attempt to reach ~/.ssh/id_rsa has nowhere to land. Local files and URLs are brought in through botholomew membot add. External capabilities (email, Slack, the web, and hundreds of other services) are granted deliberately, per project, through MCP servers wired up via MCPX.

---

Why I built this

I built the agent I wanted for my own manager-style work — the reading, summarizing, chasing-down, and remembering that fills a week. Nothing on the shelf fit, so Botholomew is opinionated on purpose:

• Memory is the point, not a feature. I load it up with every Linear project and hundreds of Google Docs and expect it to search across all of them. The knowledge store isn't bolted on — the whole agent is built around it.
• Local, including local LLMs. It runs on my machine and talks to Ollama just as happily as it talks to Anthropic.
• Real tasks, not a swarm. Durable, schedulable, monitorable tasks with DAGs — not fire-and-forget subagents. (My distributed-systems background wouldn't let me ship anything less.)
• Hyper-focused on tool use. Its reach into the outside world runs through an Arcade gateway — one authenticated door to hundreds of services, which is where most of the interesting work actually happens.

It's also nerdy by design: every prompt, task, thread, and belief is a plain file I can open, grep, and git diff. — Evan

---

Why Botholomew?

• Memory-first. The agent is built to reason over a large corpus, not a single chat. Ingest hundreds of files and URLs (PDF/DOCX/HTML → markdown) into a local membot store with hybrid BM25 + semantic search, append-only versioning, and history you can diff. Big tool responses get piped into the same store so the agent can work through megabytes of JSON without burning tokens.
• Autonomous. Background workers claim tasks, work them with Claude, and log every interaction. You can spawn one-shot workers on demand, a long-running --persist worker, or point cron at botholomew worker run.
• Portable. A project is just a directory of files — markdown for prompts, tasks, schedules, and context; CSVs for conversation history. Copy it, share it, git diff it, check it in (or .gitignore it).
• Your data, your disk. Tasks, schedules, threads, prompts, and skills are all real files you can vim, grep, and git. The knowledge store is a single local DuckDB file (index.duckdb, managed by membot) — append-only, versioned, queryable with the DuckDB CLI if you ever want to. Model calls go direct to Anthropic; any further reach is scoped to the MCP servers you add.
• Tool use, done through a gateway. External tools come from MCP servers via MCPX. Run them locally (Gmail, Slack, GitHub) — but the setup Botholomew is tuned for points a single Arcade gateway at hundreds of authenticated services, so you handle auth once instead of babysitting a server per tool. Reusable workflows are markdown "skills" (slash commands) the chat agent can also create, edit, and search at runtime.
• Safe by default. The agent has no shell and no direct filesystem access. The knowledge store is keyed by logical_path (an opaque DB string, not a filesystem path); every external capability is an MCP server you explicitly add. The remaining file-system paths the agent touches (tasks/, schedules/, prompts/, skills/) all route through a single sandbox helper (NFC normalization + lstat-walk to reject symlinks at any level).

---

Demo

A full tour of the chat TUI — every tab, slash-command autocomplete, the message queue, tool-call visualization, and the live workers panel:

---

Install

Prebuilt binary (no Bun required — one self-contained file per platform):

curl -fsSL https://raw.githubusercontent.com/evantahler/botholomew/main/install.sh | sh

macOS (arm64) and Linux (x64); on Windows grab botholomew-windows-x64.exe from the releases. Then botholomew upgrade updates it in place.

With Bun (requires Bun 1.1+):

bun install -g botholomew

Either way the CLI installs as both botholomew and bothy — the same binary, two names.

Or run the dev build from a checkout:

git clone https://github.com/evantahler/botholomew
cd botholomew
bun install
bun run dev -- --help

---

Quickstart

# 1. Initialize a project in the current directory
botholomew init

# 2a. Add your Anthropic key (Claude is the default) to config/config.json, or export it
export ANTHROPIC_API_KEY=sk-ant-...
# Embeddings always run locally.
#
# 2b. ...or initialize for a local Ollama model — no API key required:
#     ollama serve & ollama pull llama3.1:8b
#     botholomew init --force --provider ollama
# See docs/configuration.md for OpenAI-compatible endpoints (LM Studio, OpenRouter, etc.).

# 3. Queue some work
botholomew task add "Summarize every markdown file in ~/notes"

# 4. Run a worker to process the queue
botholomew worker run                  # one-shot: claim and run one task
botholomew worker run --persist        # long-running: loop until you stop it

# 5. Or chat with the agent interactively
botholomew chat

See docs/automation.md for cron-based setups if you want Botholomew to advance on its own.

---

Example configs

Two config/config.json shapes covering the common cases. Full schema in docs/configuration.md.

Anthropic (Claude — default)

{
  "models": {
    "default": {
      "provider": "anthropic",
      "model": "claude-opus-4-6",
      "api_key": "sk-ant-..."
    },
    "fast": {
      "provider": "anthropic",
      "model": "claude-haiku-4-5-20251001",
      "api_key": "sk-ant-..."
    }
  },
  "default_model": "default",
  "fast_model": "fast"
}

models is a named registry: declare as many as you like, point default_model / fast_model at two of them, then pick one per run with --model <name> on chat / worker / dream, or model: in a task's frontmatter.

Or leave api_key blank and export ANTHROPIC_API_KEY in your shell.

Ollama (fully local)

{
  "models": {
    "default": {
      "provider": "ollama",
      "model": "qwen2.5:7b",
      "base_url": "http://localhost:11434"
    }
  }
}

Declare a single entry and it becomes both the default and the fast model — no need to name the pointers.

Start Ollama first: ollama serve & then ollama pull qwen2.5:7b. No API key required. Tool calling is a hard requirement — known-good local models include qwen2.5:7b, llama3.1:8b, mistral-nemo, and command-r. For OpenAI-compatible endpoints (LM Studio, OpenRouter, vLLM, …) see docs/configuration.md.

---

What a project looks like

A project is the directory you ran botholomew init in. Every entity the agent or worker touches is a real file you can vim, grep, and git diff:

my-project/
  config/config.json                # models, tick interval, API keys
  prompts/                          # markdown files loaded into every system prompt (or keyword-loaded)
    goals.md                        #   identity + current goals (agent-editable)
    beliefs.md                      #   agent-editable priors
    capabilities.md                 #   auto-generated tool inventory
  skills/                           # slash commands (built-ins + user-defined)
    summarize.md
    standup.md
    capabilities.md
  mcpx/servers.json                 # external MCP servers (Gmail, Slack, …)
  index.duckdb                      # knowledge store (managed by membot)
  config.json                       # membot config (separate from config/config.json)
  tasks/                            # one markdown file per task
    <id>.md                         #   status & metadata in frontmatter
    .locks/<id>.lock                #   O_EXCL claim file (held by a worker)
  schedules/                        # one markdown file per schedule
    <id>.md
    .locks/<id>.lock
  threads/<YYYY-MM-DD>/<id>.csv     # full conversation history
  workers/<id>.json                 # worker pidfile + heartbeat
  logs/<YYYY-MM-DD>/<id>.log        # per-worker logs

Tasks, schedules, threads, prompts, and skills are plain text — vim, grep, and git work without ceremony. The agent's knowledge store lives in index.duckdb, managed end-to-end by the membot library: ingestion (PDF/DOCX/HTML → markdown), local WASM embeddings, hybrid BM25 + semantic search, append-only versioning, and URL refresh all live there.

---

The CLI

Command	Purpose
botholomew init	Initialize the current directory as a project (--provider anthropic|ollama|openai-compatible to preconfigure the model registry; refuses on iCloud/Dropbox/NFS without --force)
botholomew status	One-command dashboard: workers, task counts/claims, schedules (with a live "due?" check), quarantined files, store info. --json for scripting, --no-evaluate to skip the LLM schedule check
botholomew worker run|start	Run a worker (foreground or background); --persist for long-running, --task-id <id> to target one task, --model <name> to pin every task to one configured model, --unsafe to bypass the tool-approval gate
botholomew worker list|status|stop|kill|reap	Inspect and manage running workers
botholomew chat	Interactive Ink/React TUI (--model <name> to pick a configured model, --unsafe to bypass the tool-approval gate)
botholomew dream	Reflect on recent threads — consolidate learnings into the knowledge store and update beliefs/goals (--since, --dry-run, --model <name>); also /dream in chat
botholomew task list|add|view|update|reset|delete	Manage the task queue (markdown files in tasks/); --model <name> pins a task to a configured model
botholomew schedule list|add|view|enable|disable|trigger|delete	Recurring work (markdown files in schedules/); --model <name> is inherited by the tasks the schedule spawns
botholomew approval list|view|approve|deny	Review and decide pending outbound-tool approvals (markdown files in approvals/)
botholomew membot add|ls|tree|read|write|search|info|versions|diff|refresh|…	Knowledge-store passthrough to membot — --config is resolved from membot_scope (default )

All list subcommands support -l, --limit <n> and -o, --offset <n> for pagination.

---

How it works

 ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
 │    Chat      │         │  Worker(s)   │         │    cron /    │
 │   (Ink TUI)  │         │  (tick loop) │         │    tmux      │
 │              │         │              │         │    (optional)│
 └──────┬───────┘         └──────┬───────┘         └──────┬───────┘
        │                        │                        │
        │ enqueue tasks          │ pidfile + heartbeat    │ fire
        │ browse history         │ claim via O_EXCL lock  │ `worker run`
        │ spawn_worker tool      │ run LLM tool loops     │ on a
        │ invoke skills          │ reap orphan locks      │ schedule
        │                        │ log threads → CSV      │
        └────────────┬───────────┴────────────┬───────────┘
                     │                        │
              ┌──────▼────────────────────────▼──────┐
              │     <project-root>/                   │
              │       tasks/<id>.md                   │
              │       schedules/<id>.md               │
              │       threads/<date>/<id>.csv         │
              │       workers/<id>.json               │
              │       prompts/, skills/, mcpx/        │
              │       index.duckdb  ◄─ membot         │
              │       (knowledge store)               │
              └──────────────────┬────────────────────┘
                                 │
                                 ▼
                  MCPX ─► Gmail, Slack, GitHub, Firecrawl, …

See docs/architecture.md for a deeper tour.

---

Deep dives

The full docs site is published at www.botholomew.com.

Topics worth understanding in detail:

• Architecture — workers, chat, and how they share a database. Registration, heartbeat, and reaping.
• Automation — cron recipes and optional launchd/systemd samples for running workers on a schedule without a shipped watchdog.
• The TUI — the botholomew chat Ink/React terminal UI: eight tabs, slash-command autocomplete, message queue, tool-call visualization, and a live workers panel.
• Files & the knowledge store — the membot store, the path sandbox (NFC + lstat-walk) for non-knowledge files, and how membot_read/membot_write/membot_edit/membot_run work.
• Context & search — pointer to membot for ingestion, chunking, embeddings, and hybrid search.
• Tasks & schedules — markdown frontmatter as the source of truth, lockfile-based claim, DAG validation, and natural-language recurring schedules.
• The Tool class — one Zod definition, three consumers (Anthropic tool-use, Commander CLI, tests).
• Prompts — generic markdown files in prompts/, strict frontmatter validation, and full CRUD via CLI + agent tools.
• Reflection (dream) — / : consolidating recent threads into durable memory and self-edited prompts, plus episodic .

---

Tech stack

• Bun + TypeScript
• membot — owns the knowledge store: ingestion (PDF/DOCX/HTML → markdown), local WASM embeddings, hybrid BM25 + semantic search over DuckDB, append-only versioning, URL refresh. Botholomew consumes it as an SDK.
• Anthropic SDK for Claude — the reasoning model
• MCPX for external tools
• Ink 6 + React 19 for the terminal UI
• Commander.js for the CLI
• Zod for tool input/output schemas

---

Contributing

bun install
bun test
bun run lint            # tsc --noEmit + biome check

See CLAUDE.md for conventions (always use bun, bump the version in package.json on every merge to main, etc.).

---

License

MIT.