Plugin Guide

Every place a plugin can extend bb.

All plugin surfaces

Every surface in the guide, with what it lets a plugin do.

The bb app window

  • Full-page panelsAdd a navigation rail destination that opens a full page your plugin renders.
  • Thread row statusAdd a small status icon to a thread's row in the sidebar.
  • The thread listReplace the sidebar's thread list with one your plugin renders.
  • Sidebar footer itemsAdd an icon to the bottom of bb's sidebar.
  • Thread header controlsAdd a control to the header of an open thread.
  • Thread menu actionsAdd an action to every thread menu and the sidebar row's quick actions.
  • Timeline entry contentAdd rich detail to the timeline entries your plugin creates.
  • Rich message embedsAdd live components to an agent's reply.
  • Inline code-block renderersReplace fenced code blocks in an agent's reply with live UI.
  • Message actionsAdd an action to messages in a thread.
  • In-thread formsAdd a form that asks the person a question and returns the answer to the agent.
  • Code & diff renderersReplace bb's code or diff viewer everywhere it appears.
  • Browser toolbar controlsAdd a control to the toolbar of each Browser tab.
  • Thread side-panel tabsAdd a tab to the side panel next to a thread.
  • File viewers & editorsAdd a viewer or editor for the file types you choose.
  • App-wide overlaysAdd a floating widget that stays on screen across bb.
  • App-wide scriptsRun code in every bb window, without a UI of its own.

Command palette

  • Command palette actionsAdd commands to bb's command palette.

The composer

  • BannersAdd a banner above the prompt box.
  • Draft prompt state & lockingUse the draft prompt from plugin code.
  • MentionsAdd items to the menu that opens when someone types @ or another trigger.
  • Draft prompt highlightingAdd highlighting to text as someone types a prompt.
  • The + and send menusAdd rows to the + menu or the menu beside the send button.
  • Agent providersProvide an agent people can pick in bb's model picker.
  • Inline actionsAdd a button inside the prompt box, beside voice and send.

Home page

  • Home-screen sectionsAdd a section to bb's home page.
  • New-thread side panelAdd a side-panel tab to the new-thread screen.

Plugin settings page

  • Settings fieldsAdd settings fields to the plugin's settings page without writing UI.
  • Custom settings sectionAdd your own section to the plugin's settings page.

Plugin page

  • Configuration statusAdd a needs-configuration warning to the plugin's page.

Plugin backend

  • bb CLI commandsAdd a bb <name> command for people and agents.
  • Agent tools & skillsAdd tools, skills, and instructions to every agent session.
  • Background workRun code on the bb server when no window is open.
  • HTTP, WebSocket, RPC & realtimeUse RPC, HTTP, WebSocket, and realtime messages to connect the plugin.
  • Lifecycle eventsRun server code when threads change state or environments are removed.
  • Dispatch hookRun a check before each message reaches an agent.
  • Environment providersProvide new places a thread can run, picked like any environment.
  • Machine providersProvide machines that bb creates and manages, such as cloud sandboxes.
  • Machine server accessProvide the connection machines use to reach their bb server.
  • Host workersRun plugin code on enrolled machines, not only on the server.
  • Provider bridgesRun an agent's sessions through a bridge your plugin ships to each machine.
  • StorageUse storage on the bb server that only your plugin can see.
  • The bb SDKUse bb's own API from plugin server code.
  • Thread plugin metadataUse a private JSON record on each thread.
  • Desktop browser controlUse bb's desktop browser tabs from plugin code.
  • AI servicesProvide the models that write bb's titles, commit messages, and transcripts.
  • Host componentsUse bb's own chat, prompt box, and pickers inside plugin pages.
  • Testing harnessesUse test harnesses that run without bb.