bb-plugin-cat

A BB plugin that puts a black cat with white paws at the bottom of the bb window. The cat reacts to what your agents are doing, and you can pet it.

• server.ts — the backend: three settings (enabled, size, roaming) and four HTTP routes that serve the sprite sheets from assets/sheets/. The backend keeps no state; fleet state is read on the frontend.
• app.tsx — the frontend: a full-width canvas overlay pinned to the bottom of the window that draws and animates the cat.
• cat-sprite.ts — sheet loading, frame drawing, heart and Zzz effects.
• assets/sheets/*.png — the four pose sheets (walk, sit, sleep, sad), regenerated by tools/build-sheets.py.
• components/, hooks/, lib/ — vendored shadcn components.
• PLUGIN_OVERVIEW.md — the store listing text: a longer version of bb.description that the plugin detail page shows under it. See Store listing.

What the cat does

Fleet state comes from experimental_useSidebarThreads, the same live cache the built-in sidebar reads:

• any thread starting, active or stopping → the cat walks briskly across the window;
• any thread waiting on you → it sits;
• any thread errored → it sits, sad;
• quiet for 30 seconds → it falls asleep (Zzz).

Click the cat to pet it: three hearts rise, with a five-second cooldown. With roaming on, the cat strolls even while the agents are idle; with it off it only walks while agents work and sits the rest of the time. Under prefers-reduced-motion the cat keeps its pose instead of walking.

Nothing leaves the machine: no account, no API key, no external service.

UI components

components/ui/ is vendored source you own (the shadcn model): edit the files freely — they never update out from under you. Add more from the BB component registry (the full shadcn set, version-matched to your BB install via the pinned ref in components.json):

npx shadcn add @bb/select @bb/table

Run npm install once before bb plugin build — the vendored components' npm deps bundle into your dist. React, and BB-shimmed packages like the radix portal primitives and sonner (import { toast } from "sonner" reaches BB's own toaster), are provided by the BB app at runtime and never bundled. Every shimmed package is declared in devDependencies at the host's version so those imports typecheck; keep them there (never in dependencies, which would bundle a second copy), and bb plugin types repins declared packages alongside the SDK; unused packages may be removed. Ship dist/ (npm tarball or committed for git installs) so people installing your plugin never need npm.

Manifest

package.json is the plugin manifest. Notable fields:

• bb.server — backend entry (required).
• bb.app — frontend entry. Delete it, app.tsx, components/, hooks/, and lib/ for a headless plugin.
• bb.skills — skill roots; omitted here, so BB reads skills/. Each directory with a SKILL.md is one skill, named after the directory.
• bb.name and bb.description — required human-facing identity.
• bb.branding — required; declare icon as a BB icon name or a plugin-relative compact SVG, or declare logo.light (with optional logo.dark). Logo assets must be relative .svg, .png, or .webp files.
• engines.bb — supported bb app version range.
• engines.bbPluginSdk — the lowest plugin SDK you need (scaffold: >=0.6.79). BB reads this as a floor, not a ceiling: a later SDK in the same major still loads your plugin.
• dependencies — every package your source imports that BB does not provide. bb plugin build inlines them into dist/, and git installs resolve this list alone, so a build-required package here rather than in devDependencies is what keeps your plugin installable. devDependencies is for types and tooling only (BB shims React, the portal primitives, and @get-bb/plugin-sdk at runtime — never bundle them).

Run bb plugin build before publishing git/npm installs. It writes dist/server.js + server.meta.json and app.js / app.css / app.meta.json. Each *.meta.json stamps SDK major/version, artifactFormatVersion, pluginId, pluginVersion, and builtWith so managed installs can verify the artifacts.

Store listing

Two texts describe the plugin in the store. bb.description in package.json is the one-sentence hook on every browse card and the lead paragraph on the detail page; keep it under about 140 characters. PLUGIN_OVERVIEW.md is the same claim at length, shown in an Overview section under that paragraph. Rewrite the scaffold's copy for your plugin, and update it whenever bb.description changes, so the two never disagree.

The submission to the public BB Community marketplace requires the file. Keep it under 4000 characters (aim for 700 to 1800) and use headings, paragraphs, emphasis, code, blockquotes, lists, thematic breaks, and absolute https links only — raw HTML, images, tables, footnotes, and task lists are rejected. Do not open with a # title or repeat bb.description verbatim; the page shows both directly above.

Install

From this directory (bb plugin new already ran the install; a fresh clone needs it):

npm install
bb plugin install .

After editing sources, reload:

bb plugin reload cat

Or let bb plugin dev rebuild and reload on every save.

Configure

bb plugin config cat
bb plugin config cat set size large
bb plugin config cat set roaming false
bb plugin reload cat

Types & API reference

The plugin API ships as the npm package @get-bb/plugin-sdk, pinned to an exact version in devDependencies (0.6.79 — the SDK of the BB that scaffolded this plugin). After npm install, the full surface is on disk at:

node_modules/@get-bb/plugin-sdk/bundled-types/bb-plugin-sdk.d.ts      # backend
node_modules/@get-bb/plugin-sdk/bundled-types/bb-plugin-sdk-app.d.ts  # frontend

Your editor and tsc resolve @get-bb/plugin-sdk there through ordinary node resolution — no path mapping. These are readable declarations: open them for an exact signature.

The SDK surface grows with every BB release, so the pin has to track the BB you actually run:

bb plugin types          # sync this plugin's SDK surface to the running BB
bb plugin types --check  # CI: fail when it does not match

Ask BB to write plugins for you: the bb-plugin-authoring skill documents the whole surface with examples.

Confused by the API, or need something the types don't explain? Clone the BB repo and read the source: https://github.com/get-bb/bb.