Get started

This page walks you from a clean machine to a running Botholomew worker processing tasks. For deeper background, see Architecture.

Prerequisites

• Bun 1.1+ — Botholomew is a Bun-native CLI.
• An Anthropic API key — Claude is the reasoning model.
• Embeddings run locally via @huggingface/transformers (default Xenova/bge-small-en-v1.5, 384-dim). The first call downloads ~33 MB of weights to .botholomew/models/; no API key is required.
• Optional: any MCP servers you want to expose to the agent (Gmail, Slack, GitHub, etc.) — managed through MCPX.

Install

bun install -g botholomew

Or run from a checkout:

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

Initialize a project

In any directory you want Botholomew to operate inside:

botholomew init

This creates a .botholomew/ directory with templates and a fresh DuckDB database:

my-project/
  .botholomew/
    soul.md               # always-loaded identity (not agent-editable)
    beliefs.md            # always-loaded, agent-editable priors
    goals.md              # always-loaded, agent-editable goals
    capabilities.md       # always-loaded, agent-editable tool inventory
    config.json           # models, tick interval, API keys
    data.duckdb           # tasks, schedules, context, embeddings, logs
    mcpx/servers.json     # external MCP servers (Gmail, Slack, …)
    skills/               # slash commands (built-ins + user-defined)
    logs/                 # per-worker log files

Everything the agent can touch is here — see The virtual filesystem for why.

Configure API keys

Either export the environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

…or set it in .botholomew/config.json. See Configuration for every key and its default.

Queue work and run a worker

# Add a task to the queue
botholomew task add "Summarize every markdown file in ~/notes"

# Process it
botholomew worker run                  # one-shot: claim and run one task
botholomew worker run --persist        # long-running: loop until you stop it

Want it to run on its own? See Automation for cron, tmux, launchd, and systemd recipes.

Chat interactively

botholomew chat

The chat command opens an Ink/React TUI with eight tabs — chat, tasks, workers, context, schedules, threads, history, and logs — plus slash-command autocomplete, a message queue, tool-call visualization, and a live workers panel.

What's next

• The CLI reference on GitHub
• Architecture — workers, chat, shared DB
• Tasks & schedules — the claim loop and recurring schedules
• Context & hybrid search — ingest files, folders, and URLs
• MCPX integration — wire up external services
• Skills — slash-command templates the agent can also author at runtime