Skip to content
bb plugin atlas

Surfaces

bb 0.43.3SDK 0.4.104pinned e865697 (desktop-v0.43.3)

This page indexes the plugin API’s 46 surfaces in seven groups, numbered the way the built-in Plugin Guide numbers them. A “surface” is the product grouping used by that guide: PluginSurface { id, title, summary, bullets, apiSymbols, … } inside the SurfaceGroup objects. The number is the index plus one within its own group (SURFACE_NUMBERS); the headless group gets no numbers.

The visual map

The same numbers, drawn over the real bb interface (App shell · Quick palette · Home · Settings → plugin page · Plugins page), are at /map/. What follows here is the tabular index, with SDK symbols and links.

Each row carries the surface id, its SDK symbols, the first-party plugins that use it, and where it sits in the UI. Each is also a link into the map and into the slot or namespace card that implements it.

The bb app window

The main bb window, containing the sidebar, the conversation, and the side panel. A plugin can add rows, controls, panel tabs, and message content to the numbered regions.

  • Sidebar navigationexperimental Replaces bb's navigation controls above the thread list with a component your plugin renders. With this, a plugin can: on the map
  • Full-page panelsstable Adds a row to bb's sidebar that opens a page your plugin renders where threads normally appear. With this, a plugin can: on the map
  • Thread row statusexperimental A small status bb can draw on a thread's row in the sidebar. With this, a plugin can: on the map
  • The thread listexperimental Replaces the list of threads in bb's sidebar with a component your plugin renders. With this, a plugin can: on the map
  • Sidebar footer itemsexperimental Adds a host-rendered icon item to the bottom of bb's sidebar. With this, a plugin can: on the map
  • Thread header controlsexperimental Adds a control to the header bar at the top of an open thread. With this, a plugin can: on the map
  • Browser toolbar controlsexperimental Adds a plugin control to the toolbar of each open Browser tab. With this, a plugin can: on the map
  • Timeline entry contentexperimental Renders the expanded content of plugin-owned timeline entries while bb keeps each entry's header and controls. With this, a plugin can: on the map
  • Rich message embedsstable Renders your component inside an agent's reply, in place of a marker the agent writes into its message. With this, a plugin can: on the map
  • Message actionsstable Adds an action to individual messages in a thread. With this, a plugin can: on the map
  • In-thread formsstable Pauses an agent mid-turn to ask the person a question, and hands their answer back to the agent. With this, a plugin can: on the map
  • Code & diff renderersexperimental Replaces bb's source-code or diff renderer everywhere that kind of content appears. With this, a plugin can: on the map
  • Thread side-panel tabsstable Adds a tab to the side panel that opens to the right of a thread. With this, a plugin can: on the map
  • File viewers & editorsstable Registers a viewer for the file types you name, so bb opens those files there instead of its built-in preview. With this, a plugin can: on the map
  • App-wide overlaysexperimental Mounts floating plugin UI across the bb app, outside route-owned layout regions. With this, a plugin can: on the map
  • App-wide scriptsstable Runs your code inside the bb window itself, without rendering a UI of its own. With this, a plugin can: on the map

Command palette

bb's searchable command menu. A plugin can add actions that match, rank, and run alongside bb's own commands.

  • Command palette actionsstable Registers a command with app.commands.register and adds a row under Plugins in bb's quick command palette. With this, a plugin can: on the map

The composer

The prompt box used to start a thread and to reply inside one. A plugin can add banners, menu entries, and action buttons to it, answer mention searches, highlight the draft prompt, and supply the agent that runs the message.

  • Bannersstable Renders a banner above the prompt box. With this, a plugin can: on the map
  • Mentionsstable Adds results to the menu that opens when someone types a trigger character in the prompt box. On a trigger bb does not use itself, your plugin opens that menu and owns it. With this, a plugin can: on the map
  • Draft prompt highlightingstable Styles text ranges as the person types a prompt, without changing the text. With this, a plugin can: on the map
  • Draft prompt state & lockingstable Reads the draft prompt, and can block typing while the plugin works. With this, a plugin can: on the map
  • The + menustable Adds rows to the menu that opens from the + button beside the prompt box. With this, a plugin can: on the map
  • Agent providersexperimental Adds an agent to bb's model picker and runs the threads started with it. With this, a plugin can: on the map
  • Inline actionsstable Adds a button to the row of controls inside the prompt box, beside the voice and send buttons. With this, a plugin can: on the map

Plugin page

The page bb shows for an installed plugin under Plugins: what it is, what it registers, and whether it is healthy. A plugin can report that it needs configuring, and bb says so at the top of this page.

  • Configuration statusstable Reports that the plugin cannot run until someone configures it, so bb can say so instead of the plugin failing silently. With this, a plugin can: on the map

Plugin backend

The parts of the plugin API with no interface of their own.

Commands & agent capabilities

Running & reacting

Data & platform

  • Storagestable Stores the plugin's data on the bb server. With this, a plugin can: on the map
  • The bb SDKstable Calls bb's own API from the plugin's server code. With this, a plugin can: on the map
  • Thread plugin metadatastable Stores namespaced plugin JSON for a thread without automatically exposing it to the model. With this, a plugin can: on the map
  • Desktop browser controlexperimental Controls a selected desktop window through bb.sdk.experimental_desktopBrowsers. With this, a plugin can: on the map
  • AI servicesexperimental Lets a plugin answer bb's own helper-model calls — the short model calls behind thread titles and commit messages, and the microphone button's transcription. With this, a plugin can: on the map
  • Host componentsstable Renders bb's conversation, prompt box, and shared app icons inside plugin pages. With this, a plugin can: on the map

Confidence

Home page

The screen bb opens on, holding the new-thread composer and a side panel. A plugin can add a section below the composer, and an action in that panel that opens its own tab.

Plugin settings page

The settings page bb creates for every installed plugin. A plugin can declare fields for bb to render and add its own section below them.

  • Settings fieldsstable Declares the settings your plugin needs as plain data; bb renders the form for them on the plugin's settings page and stores the values. With this, a plugin can: on the map
  • Custom settings sectionstable Renders your own React component on the plugin's settings page, below the fields bb generated. Use it for anything that is not a value in a form. With this, a plugin can: on the map