Hooks

Automate thread events. Gate messages on your terms.

Run shell commands or call webhooks when BB events happen.
Control message dispatch and inspect hook runs from one place.

The problem · Features · Install · Where to find it · How it works · Privacy and control · CLI · Settings · Development · Licence

Note

Screenshots are real BB captures populated with fictional demo data.

The problem

Without Hooks, you have to connect BB events to your own scripts and keep those integrations in sync. Messages also go straight to the agent unless you build a separate dispatch gate.

Hooks gives you one place to create, test and manage those automations.

	Without Hooks	With Hooks
React to thread events	Check manually or wire up a separate integration	Run a command or send a webhook
Control message dispatch	No custom gate	Proceed, reject or wait before the message reaches the provider
Set up common integrations	Write each hook yourself	Configure a template, or add one from a catalog

Features

🪝 React to BB events Run shell commands or send HTTP requests when threads start, finish, fail, need you, or change state.	🛡️ Gate message dispatch Check each outgoing message before it reaches the provider. Let it through, reject it with a reason, or wait.
🧰 Start from the marketplace A fresh install includes no hooks. Templates come from the marketplace catalog subscribed by default. Add another catalog when you need more.	🔐 Keep secrets encrypted Store credentials separately from hook definitions. Commands receive secrets as environment variables; webhooks substitute them when sending a request.
🧭 Manage hooks in BB Browse the marketplace, edit and test installed hooks, manage catalog sources and secrets, and inspect recent runs from the Hooks page.	🤖 Work from the CLI or an agent Use bb hooks in a terminal. The bundled skills help agents create hooks from a request, test them and explain the result.

Manage and test installed hooks	Configure a hook in the editor
Store and rotate credentials	Look up events and payloads

Templates

Installing the plugin does not install any hooks. The default catalogs setting subscribes to MacHatter1/bb-hooks-marketplace. The Hooks page groups those templates by category, shows the author, and scores performance and security out of 100. The letter uses the usual scale: A+ is 97–100, then A, A-, B+, B, B-, and so on down to F.

Install

bb plugin install git:https://github.com/MacHatter1/bb-plugin-hooks --yes

This repository is private. Git installs need GitHub credentials on the machine running BB.

Install from a local clone

git clone https://github.com/MacHatter1/bb-plugin-hooks.git
cd bb-plugin-hooks
npm install && bb plugin build
bb plugin install path:$PWD --yes

Requirements

• bb 0.43+ (runtime SDK 0.4.87+; development pin 0.5.9)
• Node.js and npm for a local build

Where to find it

Where	What
Sidebar → Hooks	Browse templates, manage installed hooks and catalogs, store secrets, and read the reference.
Composer → + → Create a hook	Describe what you want; a new thread opens with the bundled create-hook skill.
Settings → Installed plugins → Hooks	Inspect or edit the hooks JSON setting.
Terminal or agent	Run bb hooks to manage, test and inspect hooks.

How it works

flowchart LR
  E["BB event"] --> M{"Hooks enabled and filters match?"}
  M -- No --> X["No hook runs"]
  M -- Observe --> O["Run matching hooks"]
  O --> T["Shell command or HTTP POST"]
  T --> H["Keep run result when history is enabled"]
  M -- "message.dispatch gate" --> G["Run gate hooks"]
  G --> H
  G --> D{"Decision"}
  D -- Proceed --> P["Message reaches provider"]
  D -- Reject --> R["Reject the message"]
  D -- Wait --> W["Queue the message"]

Loading

• One shared definition. The Hooks page, settings and bb hooks all manage the same hook list.
• Runs on the BB server. Commands receive event JSON on stdin; webhooks get a JSON POST, with an optional body template. Commands do not run inside the thread's environment.
• Filter and bound runs. Match by project, provider, title or text. Hooks without a custom timeout default to 30 seconds; the maximum is 10 minutes, and dispatch gates are capped at 8 seconds.
• Choose the gate outcome. Exit codes 0, 2 and 3 mean proceed, reject and wait. A JSON decision on the last output line is also supported; errors proceed by default unless you set onError.

Privacy and control

• 🖥️ Commands run with the BB server's access. They run on the machine hosting BB, as its user; review commands and catalog templates before installing them.
• 🔑 Secrets stay out of hook definitions. Values are encrypted with AES-256-GCM in the plugin database and resolved only when a hook runs. Run history and test output redact those values.
• 🌐 You choose the plugin's HTTP destinations. URL hooks send event JSON to the endpoint you configure. Shell commands run with the server user's access and can make their own network requests. Configured catalogs are fetched by the server; catalog templates require confirmation before installation.
• ⏱️ Gate hooks have a time limit. Each gate run is capped at 8 seconds so it cannot hold message dispatch indefinitely.
• 📊 Install counts are opt-in, and only for the BB Hooks Marketplace. BB asks before sending any, then reports only the template id and version of each new install from that catalog. Installs from other catalogs are never reported. Change your answer with bb hooks marketplace stats on|off.

CLI

bb hooks templates
bb hooks use desktop-notify
bb hooks list
bb hooks add no-prod --event message.dispatch --command 'echo "Production needs a human." >&2; exit 2'
bb hooks test no-prod
bb hooks history --limit 20

All commands

Command	Does
list [--json]	List installed hooks.
events [--json]	List events and their meanings.
templates [<template>] [--search <text>] [--json]	Search templates or show one.
use <template> [--set key=value]… [--id id] [--event event]… [--project id] [--provider id] [--title regex] [--text regex] [--disabled] [--yes]	Create hooks from a template. Catalog templates require --yes.
marketplace list|add <src>|remove <src>|refresh [src]|search <text>|validate <src>|init [--name catalog]	Manage and validate catalog sources.
marketplace stats [on|off|ask]	Show or change whether new installs from the BB Hooks Marketplace are reported to its install counter.
secrets list|set <name> <value>|remove <name>	Manage encrypted secrets.
show <id>	Show a hook as JSON.
add <id> --event <event> (--command <shell> | --url <url>) [--project id] [--provider id] [--title regex] [--text regex] [--timeout ms] [--cwd dir] [--header k=v]… [--on-error proceed|reject|wait] [--description text] [--disabled]	Create a hook.
edit <id> [same flags as add] [--clear-match]	Change a hook.
enable <id> / disable <id>	Enable or disable a hook.
remove <id>	Delete a hook and secrets used only by it.
test <id> [--thread <thread_id>] [--json]	Run a hook with a sample payload or a real thread.
history [--limit n] [--hook id] [--json] / history clear	Read or clear run history.
export <id>	Print a hook as a template for a catalog.

Agent access: BB registers the bb hooks CLI for agents. The bundled hooks skill documents events and commands; create-hook guides an agent from a request through a tested hook.

Settings

Configure with bb plugin config hooks, or Settings → Installed plugins → Hooks.

All settings

Setting	Default	Effect
hooks	[]	Validated JSON array of hook definitions.
enabled	true	Master switch. Off keeps definitions but runs no hooks.
historyLimit	200	Number of runs to keep; 0 disables history. Range: 0–10,000.
maxConcurrent	8	Maximum concurrent observe-hook runs; applies after reload. Range: 1–64.
webhookSecret	unset	Optional HMAC-SHA256 signing secret for webhook requests.
catalogs	MacHatter1/bb-hooks-marketplace	Catalog sources, one per line. The plugin refreshes them periodically.
shareInstalls	ask	Whether to report new BB Hooks Marketplace installs to its install counter: ask (BB asks on the first one), on or off.
secretsKey	generated on first load	Encryption key for stored secrets. Changing it makes existing secrets unreadable.

Turning it off

Use the switch in the Hooks page to pause runs while keeping the plugin enabled. To disable or remove the plugin:

bb plugin disable hooks
bb plugin enable hooks
bb plugin remove hooks

Development

npm install
npm test
npm run typecheck
bb plugin build
bb plugin install path:$PWD --yes
bb plugin dev

server.ts   settings, RPC, CLI and event listeners
app.tsx     sidebar, settings and composer slots
src/        hook definitions, runner, secrets, catalogs and UI
components/ shared UI components
skills/     bundled agent skills
assets/     icon, screenshots and social preview
docs/       README logo

Tests cover definitions, template rendering, catalog behaviour, secret storage, the runner and server event handling with a fake plugin host.

PLUGIN_OVERVIEW.md is the store listing. Keep it in step with bb.description in package.json.

Licence

MIT