Getting Started

Beekeeper is threat intelligence for autonomous coding agents. It evaluates an agent's tool calls before they execute, blocking malicious package installs and sensitive-path credential reads. This guide takes you from nothing to a working beekeeper check in five steps.

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 a pinned release with a single command. Beekeeper is a supply-chain security tool, so it pins an exact version rather than a mutable @latest. Bump the tag when you upgrade.

go install github.com/home-beekeeper/beekeeper/cmd/beekeeper@v1.2.0

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 turns on install posture: three rules (release age, lifecycle scripts, and git or remote-URL dependencies) that check every package install the agent runs, whichever package manager it uses. All three warn by default and fail soft, so a registry timeout warns rather than blocks. Opt a rule up to block, or grant scoped exceptions, with beekeeper posture. See Configuration for the rules and overrides.

5. Verify it works

beekeeper check evaluates a single tool call and decides whether to allow, warn, or block it. The quickest smoke test builds the call from flags, so it runs the same in any shell:

beekeeper check --hook claude-code --tool Bash --args "cat ~/.ssh/id_rsa"

This attempts a credential read. You get a deny (sensitive path blocked: /.ssh/) and exit code 2. A benign call such as --args "ls" exits 0.

A harness hook feeds the call as JSON on stdin instead. The same check, the way Claude Code actually invokes it (bash):

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

PowerShell. Windows PowerShell does not reliably pipe text into a native program's stdin, so the echo ... | beekeeper check form can report invalid tool call JSON. Use the flag form above (--tool / --args), which needs no stdin. Also never end a line with \ to wrap a command in PowerShell: that is a bash-only continuation and is what makes a copied multi-line command fail.

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.

What to expect

Beekeeper records every decision (allow, warn, or block) in the audit log at ~/.beekeeper/audit/beekeeper.ndjson. The file is NDJSON (one JSON object per line), so for a readable view, export it as a table or filter it rather than dumping the whole thing:

beekeeper audit export --format csv --since 24h

beekeeper audit query --decision block --limit 20

beekeeper audit tail --no-follow dumps every record, including bulk package-inventory records written by beekeeper scan, so it can be very long and hard to read by eye; prefer export / query above, or the color-coded audit viewer in beekeeper dashboard.

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 end to end: hook fires, the tool call is blocked, the block is audited. The other 16 harnesses are built to their published contracts and contract-shape tested, but not run against a real harness in CI. Integration has the per-harness breakdown and each tier's caveat.