bb plugins

bb plugins are TypeScript packages that run inside bb. They are how bb extends itself.

Many first-party features are plugins: GitHub, Docs, Memory, Tasks, Connect, Automations, Secrets, Keep Awake, and the coding-agent providers.

Trust

Plugins are full-trust. Server code runs in-process. App UI is same-origin page code, not a sandbox. Host workers run as Node on enrolled machines.

Review source before installing third-party plugins. Keep credentials in secret: true settings.

This skill vs others

• Use this skill to create, install, or change a plugin.
• Use bb-cli to operate bb (threads, projects, environments).
• For exact API signatures, read the bb-plugin-authoring skill if it is available, then run bb guide plugins. In the plugin directory, run bb plugin types before trusting local SDK types. Do not guess from minified dist/ files.

Scaffold

bb plugin new hello            # add --app for a React UI
cd bb-plugin-hello
bb plugin install . --yes
bb plugin dev                  # rebuild + reload on save

The manifest is the bb object in package.json. Required: bb.name, bb.description, bb.branding.icon, bb.server. Optional: bb.app, bb.host, bb.skills, bb.themes.

Plugin id is the last package-name segment with a bb-plugin- prefix stripped. bb-plugin-hello and @acme/bb-plugin-hello both become hello.

Put runtime imports in dependencies. Leave types and tooling in devDependencies. Git installs run npm install --omit=dev.

What a plugin can add

A default-export factory in server.ts receives BbPluginApi and registers surfaces:

• settings, kv + SQLite storage, HTTP, RPC, realtime
• background services and cron
• one top-level bb <name> … command
• agent tools, skills/ folders, extra instructions
• mention providers
• optional host workers and experimental agent providers