Getting Started

Beekeeper is threat intelligence for autonomous coding agents. It intercepts an agent's tool calls before they execute and evaluates them against unified threat intelligence: blocking malicious package installs, sensitive-path reads, and off-task actions. This guide takes you from nothing to a working beekeeper check.

Prerequisites

• Go 1.25 or newer (Beekeeper installs via go install)
• A supported OS: Linux, macOS, or Windows
• An agent harness to protect. This guide uses Claude Code, the one harness Beekeeper is live-verified against (see the caveat at the end)

1. Install

Install the latest release with a single command:

go install github.com/home-beekeeper/beekeeper/cmd/beekeeper@latest

This produces a single static binary on your PATH with no separate runtime to install. See Installation for signed pre-built binaries and cosign / SLSA verification.

2. Initialize

beekeeper init

beekeeper init creates the Beekeeper state directory (~/.beekeeper/ on Linux/macOS, %APPDATA%\beekeeper\ on Windows) and detects installed editors so it can offer to disable risky extension auto-update and register watch directories. For a scripted, non-interactive install:

# --yes auto-consents to all prompts; --no-editors skips editor detection
beekeeper init --yes --no-editors

3. Sync the threat catalog

beekeeper catalogs sync

This fetches the threat-intel catalogs and builds the on-disk mmap index that beekeeper check reads on every call. Run this before your first check: without an index the engine has nothing to corroborate against.

To keep catalogs fresh without re-running sync by hand, install the background sync daemon: an unprivileged per-user schedule that refreshes on an interval (default 2h, configurable). See Configuration for the catalog_sync block.

beekeeper catalogs daemon install

Where the threat intel comes from. Beekeeper's threat intelligence is inspired by Perplexity's Bumblebee project. catalogs sync fetches Bumblebee's threat_intel feed over the GitHub API and caches it locally. Here Bumblebee is a catalog source (plain data over HTTP), not a binary Beekeeper runs, so it behaves identically on every OS.

Separately, the optional beekeeper scan inventory shells out to a scanner binary on your PATH. It prefers bumblebee (the upstream tool, and the recommended scanner on macOS and Linux) and falls back to pollen (a Windows-focused fork of Bumblebee) when bumblebee is not found. On Windows that fallback is what runs, because Bumblebee has no native Windows build yet: Pollen is a Windows-only stopgap until upstream ships Windows support. Either way the catalog arrives over HTTP and the scanner runs natively, so no platform is locked out of Beekeeper's threat intelligence.

4. Install the hook for your harness

beekeeper hooks install --target claude-code

This registers Beekeeper as a PreToolUse (and PostToolUse) hook in Claude Code's configuration, merging into any existing hooks without clobbering them. The flag is --target <harness>, not --hook (that flag belongs to beekeeper check).

Installing the hook is an explicit "protect this machine" action, so on first install Beekeeper enables supply-chain enforcement: it sets nudge.mode=block in your config, which denies npm / yarn installs and steers the agent toward pnpm or bun. To opt down to advisory-only, run beekeeper config set nudge.mode soft. See Configuration.

5. Verify it works

beekeeper check reads a tool-call JSON object from stdin and decides whether to allow, warn, or block it. Pipe a credential-read attempt in to see a block:

echo '{"tool_name":"Bash","tool_input":{"command":"cat ~/.ssh/id_rsa"}}' \
  | beekeeper check --hook claude-code

With --hook <harness>, a blocked call exits 2, writes the human-readable reason to stderr, and emits the harness-specific deny JSON to stdout. An allowed call exits 0. Input is always read from stdin.

What to expect

Every decision (allow, warn, or block) is recorded in the audit log at ~/.beekeeper/audit/beekeeper.ndjson. Inspect it any time:

beekeeper audit tail --no-follow

See the Audit Log docs for querying and exporting, and Security for how block decisions are made (the corroboration model) and what Beekeeper does not defend against.

A note on harness coverage

Only Claude Code is live-verified. On the development machine, Beekeeper was confirmed end-to-end: the hook fires, the credential-read tool call is blocked (the tool does not run), and the block is written to the audit log. The other 16 supported harnesses are implemented against their published contracts and validated by contract-shape tests, but those tests do not run a real harness, so whether a given harness honors the contract in a live session is not verified in CI. See Integration for the full per-harness breakdown and the caveats for each tier.