Get started

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

Prerequisites

• An Anthropic API key — Claude is the reasoning model.
• Bun 1.1+ — only for the npm/source installs below; the prebuilt binary bundles its own runtime and needs neither Bun nor Node.
• Embeddings run locally via @huggingface/transformers (default Xenova/bge-small-en-v1.5, 384-dim). The first call downloads ~33 MB of weights into the project's models/ directory; no API key is required.
• Optional: any MCP servers you want to expose to the agent (Gmail, Slack, GitHub, etc.) — managed through MCPX.

Install

Prebuilt binary (no Bun required)

Downloads the single self-contained executable for your platform from the latest release and installs it as botholomew (with a bothy alias):

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

macOS (arm64) and Linux (x64) are supported. On Windows, download botholomew-windows-x64.exe from the releases page. Update in place anytime with botholomew upgrade.

With Bun (npm registry)

bun install -g botholomew

Either way the CLI installs as both botholomew and bothy — the same binary, two names. Examples in these docs use botholomew; substitute bothy if you prefer the shorter form.

From a checkout

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

From a checkout you can also compile the standalone binary yourself:

bun run build      # → dist/bothy (one self-contained file; runs anywhere)

It bundles everything — including DuckDB's native library and the local embedding runtime — into one file. Cross-compile for another platform with bun run scripts/build.ts --target=bun-linux-x64 (and the matching arch); CI builds this matrix and attaches the binaries to each release.

Initialize a project

In any directory you want Botholomew to operate inside:

botholomew init

This creates a project tree in the current directory — 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, scope settings
  prompts/                          # markdown 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)
  tasks/<id>.md                     # tasks (status in frontmatter)
  schedules/<id>.md                 # schedules
  threads/<YYYY-MM-DD>/<id>.csv     # conversation history
  workers/<id>.json                 # worker pidfile + heartbeat
  logs/<YYYY-MM-DD>/<id>.log        # per-worker logs

By default the knowledge store (membot) and MCP server config (mcpx) are shared globally at ~/.membot/ and ~/.mcpx/, so personal knowledge and authenticated MCP servers carry across every Botholomew project on the machine. Pass --membot-scope=project or --mcpx-scope=project to botholomew init (or flip the corresponding key in config/config.json later) to use project-local <projectDir>/index.duckdb and <projectDir>/mcpx/ instead. See Configuration → Per-project vs. global.

The agent has no shell and no filesystem-path surface to its knowledge store — every entry is addressed by logical_path (an opaque DB key). See The knowledge store for the full tool surface, and Context & search for how ingestion / search / versioning work via membot.

init refuses to run on iCloud/Dropbox/OneDrive/NFS volumes (they break the atomic-rename and O_EXCL guarantees that tasks/schedules depend on). Pass --force to override.

Configure your LLM

Botholomew speaks to language models via the Vercel AI SDK and supports three providers out of the box: Anthropic (Claude, the default), Ollama (local), and any OpenAI-compatible endpoint.

Anthropic (default)

Either export the environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

…or set api_key on the models.default entry in config/config.json.

Run fully locally with Ollama

# 1. Start Ollama and pull a tool-capable model
ollama serve &
ollama pull llama3.1:8b

# 2. Initialize a project pre-configured for Ollama
botholomew init --provider ollama

That writes a models registry with a default entry on llama3.1:8b and a fast entry on qwen2.5:3b. No API key needed. Tool-capable models include llama3.1:8b, qwen2.5:7b, mistral-nemo, and command-r. Models without the tools capability are refused when a session or task starts.

OpenAI-compatible endpoint

botholomew init --provider openai-compatible

then edit config/config.json to set base_url and api_key on each models entry for your endpoint (OpenRouter, LM Studio, vLLM, Groq, Together, etc.).

Keep several models on hand

models is a named registry, so you can declare as many as you like and pick one per run instead of editing config to switch:

botholomew chat --model fast          # cheap model for a quick question
botholomew worker run --model fast    # routine queue work
botholomew task add "deep research" --model default

See Configuration for the full schema and the --model precedence rules.

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, Tools, Context, Tasks, Threads, Schedules, Workers, and Help — 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 project directory on disk, search-index sidecar
• 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