Connect AgentBee to your AI

One step per tool. After that, you just tell your agent in plain English which actions to gate, and the bee does the rest.

The one rule: AgentBee is a USB device, so it gates where your agent's actions actually run, on your machine. Any local agent works (Claude, Codex, Gemini, an Agents-SDK app). A cloud chat window in a browser cannot reach a USB key on your desk, and neither can anything else, that is the whole point. Connect it to the runtime, not the chat box.

Find your bee's port first: ls /dev/cu.usbmodem* on macOS, or ls /dev/ttyACM* on Linux. Use it as AGENTBEE_PORT below.

Claude (Code / Desktop) MCP

One command, then just ask Claude to gate things.

claude mcp add agentbee \
  --env AGENTBEE_MODE=usb --env AGENTBEE_PORT=/dev/cu.usbmodemXXX \
  -- npx -y @agentbee/mcp

Then say: "Gate my critical actions with AgentBee."

OpenAI Codex CLI MCP

Append the server to your config (paste-safe, one line):

printf '\n[mcp_servers.agentbee]\ncommand = "npx"\nargs = ["-y", "@agentbee/mcp"]\nenv = { AGENTBEE_MODE = "usb", AGENTBEE_PORT = "/dev/cu.usbmodemXXX" }\n' >> ~/.codex/config.toml

codex mcp list     # confirm 'agentbee' is listed
codex

Then ask: "Use the agentbee request_approval tool before any destructive action."

Gemini CLI MCP

gemini mcp add -s user --trust \
  -e AGENTBEE_MODE=usb -e AGENTBEE_PORT=/dev/cu.usbmodemXXX \
  agentbee npx -y @agentbee/mcp

gemini mcp list

Any MCP client (OpenAI Agents, Cursor, Zed, …) MCP

Add this server to the client's MCP config:

{
  "mcpServers": {
    "agentbee": {
      "command": "npx",
      "args": ["-y", "@agentbee/mcp"],
      "env": { "AGENTBEE_MODE": "usb", "AGENTBEE_PORT": "/dev/cu.usbmodemXXX" }
    }
  }
}

No MCP? (Aider, scripts, CI) HOOK

Gate at the action instead. A git pre-push hook so pushing to main needs a hold:

npx -y @agentbee/cli install-hook pre-push   # drops the gate + hook into .git/hooks

Or in your own code: npm i @agentbee/sdk and call await bee.approve({action, scope, trust}) before the risky step.

Use any guard npm

The guards are reusable, tested, signed, Apache-2.0 risk classifiers that decide which actions need the bee. Pull them in once and pick the ones you want:

npm i @agentbee/guards

const { decide } = require("@agentbee/guards");
const d = decide(toolName, args, ctx);     // -> { tier, label, guard } | null
if (d) gateOnBee(d.label, scope, d.tier);  // a human must HOLD the bee

Anyone can write a new guard (one function + tests) and share it. Every release is digitally signed; verify with the bundled SIGNING.md. Browse them on npm.

Two things worth knowing

AGENTBEE_MODE=usb is required. Without it the server fails closed and will not auto-approve. Simulator mode (auto-approve, no human) is dev-only and must be turned on with AGENTBEE_ALLOW_SIMULATOR=1.
Cooperative vs enforced. The MCP request_approval tool relies on the model choosing to call it. For un-bypassable gating, use the hook path (or a PreToolUse hook): it intercepts the action whether or not the model cooperates.