Choosing a surface
A surface is one place a plugin appears or acts: a page in the sidebar, a button beside the prompt box, a tool in the agent’s session. bb names 46 surfaces in seven groups. To choose, start from what the person or the agent should experience, open a first-party plugin that already does it, and then read the surface’s reference page for the exact API. The tables below cover the common goals; all 46 surfaces are on Surfaces, and the UI zone map shows the window surfaces in place.
Four questions
Section titled “Four questions”A plugin can answer yes to several of these; the scaffold in Your first plugin answers the first two.
- Does a person see or click it in the bb window? Then you need an app entry. The surfaces are in the first six groups: the app window, the command palette, the composer, the home page, the plugin’s settings page and the plugin page.
- Does the agent use it while it works? Then the server entry gives the agent a CLI command and a skill that teaches it, a native tool, or instructions.
- Does it run with nobody watching? Then the server entry runs background services and schedules, reacts to thread events, and serves HTTP routes for outside services.
- Does it change which agent runs, or where? Agent, environment and machine providers are extension points; agent providers and the first-party environment providers also ship a host entry.
In the bb window
Section titled “In the bb window”| To add… | Surface | Plugin to read |
|---|---|---|
| a page of your own, opened from the sidebar | Full-page panels | tasks, github; the smallest is plugin-api-tester |
| a tab in the panel beside a thread | Thread side-panel tabs | side-chat, github |
| a component inside the agent’s reply | Rich message embeds | inline-vis, the smallest |
| a form that pauses the agent to ask the person | In-thread forms | ask-user-question, secrets |
| an action on a single message | Message actions | side-chat |
| a viewer or an editor for a file type | File viewers & editors | pdf-preview, the smallest; monaco-editor |
| an item at the bottom of the sidebar | Sidebar footer items | connect |
| rows in the + menu beside the prompt box | The + menu | drafts, scheduled-send |
| a banner above the prompt box | Banners | provider-retry, workflows |
| results in the mention menu | Mentions | github, tasks |
| a command in the command palette | Command palette actions | monaco-editor |
| a section on the home screen | Home-screen sections | no first-party plugin uses it |
| a replacement for the thread list | The thread list | replacement-lab-alpha with replacement-lab-beta; install both |
| settings the person fills in | Settings fields | custom-instructions, github |
| your own component on the settings page | Custom settings section | keep-awake, memory |
| a notice that the plugin needs configuring before it can run | Configuration status | github, workflows |
Your UI shares the window with bb’s own in one of four ways. On an additive surface your component sits next to bb’s components and those of other plugins. A replacement surface swaps out a bb component and falls back to it if yours crashes. The thread list is exclusive: one plugin replaces the whole list. And for host chrome such as sidebar footer items, bb draws the control from data your plugin supplies. The four kinds are defined on Frontend slots.
For the agent
Section titled “For the agent”| To give the agent… | Surface | Plugin to read |
|---|---|---|
| a command it runs, taught by a skill | bb CLI commands | the scaffold; memory, tasks |
| a native tool in its session | Agent tools & skills | ask-user-question, memory |
| instructions only, with no UI | Agent tools & skills | custom-instructions, bb-guide |
| a gate that decides whether a message may be sent | Dispatch hook | concurrency-limit |
| data that travels with the thread | Thread plugin metadata | workflows |
With nobody watching
Section titled “With nobody watching”| To run… | Surface | Plugin to read |
|---|---|---|
| a long-running service or a cron schedule | Background work | automations, keep-awake |
| code when a thread starts, finishes or fails | Thread lifecycle events | push-notifications, provider-retry |
| a webhook endpoint with signature checking | HTTP, WebSocket, RPC & realtime | slack-bot, an example with no dependencies |
| your own SQLite database with migrations | Storage | memory, github, tasks |
| code that creates threads and projects | The bb SDK | automations, tasks |
Where and how the agent runs
Section titled “Where and how the agent runs”| To provide… | Surface | Plugin to read |
|---|---|---|
| a new agent in the model picker | Agent providers | provider-acp, provider-pi; the smallest is the echo-provider example |
| the place a thread’s workspace lives | Environment providers | environment-git-worktree, environment-project-checkout |
| a machine to run threads on | Machine providers | environment-modal-sandbox |
| your own code on the agent’s machine | Host workers | keep-awake, environment-personal-workspace |
The fullest first-party reference is tasks. The catalog lists every first-party plugin with its entries and size.