Hooks

MacHatter1Tasks & Workflows
Get it for macOS

Run your own commands and webhooks when BB threads change state, and hold each outgoing message to your own policy. Install notification, integration, automation and guard templates from the marketplace catalog, each rated for performance and security, or write hooks by hand. React to thread lifecycle events with filters on project, provider, title and text; gate hooks proceed, reject with a reason, or wait before dispatch. Secrets stay AES-256-GCM encrypted and are referenced without storing values in hook definitions; manage everything from the Hooks page, `bb hooks`, or the bundled agent skills. Commands run on the machine hosting the BB server with the server user's access.

Overview

View source

Hooks runs your shell commands or sends webhooks when BB thread events happen. Add a gate on message.dispatch to let messages through, reject them with a reason, or wait before they reach the provider.

What you can do

  • Start from a template: the plugin ships no hooks of its own. Browse the marketplace catalog, which is subscribed by default, and install from there.
  • Browse catalogs: add other GitHub repositories or HTTPS catalog URLs, then search and install their templates.
  • Protect credentials: secrets are encrypted in the plugin database and referenced from hooks without storing their values in the hook definition.
  • Choose the match: react to thread lifecycle events, filter by project, provider, title or text, or check each outgoing message before dispatch.
  • Use the interface you prefer: manage and test hooks from the Hooks page, bb hooks, or an agent using the bundled skills.

How it works

Hooks live in the plugin settings. Commands run on the machine hosting the BB server and receive event JSON on stdin; webhooks get a JSON POST, with an optional body template, and do not follow redirects. Observe hooks run after events. Gate hooks run before dispatch and can proceed, reject or wait. Gates have an 8-second time limit and proceed on errors by default. An unexpected exit code is named in the reason.

The server fetches configured marketplace catalogs periodically. 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. Catalog templates require explicit confirmation before installation.

For agents

The hooks skill documents events, payloads and the bb hooks CLI. The create-hook skill turns a request into a configured and tested hook; the New hook action opens a thread with that skill.

More from MacHatter1

Agent TVSee what every running agent is doing, and which one needs you, from a live wall at the foot of the sidebar. Each tile shows the tool call in flight, the files touched in the last minute, a 60-second activity trace, and how much of its context window the thread has used. Threads blocked on a question or an approval are marked and sorted to the top. Pop the wall out as a monitor you can drag anywhere in BB. The bb agent-tv status command gives terminals and agents the same feed, and nothing leaves your BB server.NewAnimationPlay technical diagrams as a sequence of beats, then export a looping HTML page. Open a .scene.json file to get a stage and a timeline: drag a step boundary to retime it, or click a part to quote its state into chat. Agents write the same JSON with ordinary file edits. GIF and MP4 export are not included; HTML is the shareable output. Requires BB 0.43 or later.NewRecapGenerates concise, display-only summaries for BB threads on demand or after they become idle.143Context HealthSee what contributes to your thread’s context usage. Search recorded text, inspect observed skill reads and browse available skills. Optional Codex session detail reads logs on the thread host; no separate account or paid service is required.84

More in Tasks & Workflows 46

Plan, track, route, schedule, or automate work.

View all