Как работает bb
bb — это три вида процессов: сервера, который хранит всё состояние, окна приложения, где вы работаете, и демона хоста на каждой машине с агентом. Плагин добавляет код в один или несколько таких процессов. Здесь описаны сами процессы и объекты, которыми bb управляет внутри них. О том, как код плагина распределяется между ними, читайте на странице Как работает плагин.
Client: the bb app window (web, desktop, mobile) and the bb CLI
the bb app window and the bb CLI
threads, the composer, the sidebar, settings
bb <command>, typed by a person or run by the agent
↓ HTTP API → the bb server
bb.app · app entry
your UI, mounted in the same window
↓ RPC → bb.server · server entry
Server: one per installation, SQLite is the source of truth
the bb server
projects, threads, settings, plugins
the HTTP API and WebSocket /ws
127.0.0.1 by default
↓ WebSocket /ws → the bb app window and the bb CLI (signal back)
↓ thread commands → the host daemon
bb.server · server entry
required
your logic, inside the server process
↓ host RPC → bb.host · host entry
Host daemon: one per machine that runs agents
the host daemon
starts the agent provider process
the thread’s workspace directory is on this machine
enrolls with the server as a host
↓ events back → the bb server (signal back)
bb.host · host entry
optional
your code on that machine
Три процесса
Заголовок раздела «Три процесса»Сервер — это Node-процесс с базой SQLite в качестве источника истины. Он хранит каждый проект, тред, настройку и установленный плагин, отдаёт HTTP API, обслуживает один WebSocket и по умолчанию слушает 127.0.0.1. Остальные компоненты bb обращаются к состоянию через сервер.
Окно приложения — клиент сервера: веб-интерфейс, десктопное или мобильное приложение. Оно запрашивает данные по HTTP и получает изменения пушами через WebSocket. CLI bb — тоже клиент сервера. Как и агент: он связывается с bb через CLI, а также через инструменты и скиллы, которые выдаёт ему bb. Когда агент запускает bb hello add, эта команда проходит тот же путь, что и введённая человеком.
Демон хоста работает на каждой машине, которая выполняет задачи, включая саму машину сервера. Он запускает процесс агента (bb называет его провайдером агента), держит рабочие каталоги тредов и поддерживает WebSocket-сессию с сервером. Машина, которую создаёт провайдер машины, запускает собственный установленный демон, и тот регистрируется на сервере.
Чем управляет bb
Заголовок раздела «Чем управляет bb»Проект группирует работу вокруг репозитория и содержит его gitRemoteUrl. Работа вне проекта всё равно привязана к проекту — личному, с kind: "personal".
Тред — единица работы. Он содержит один диалог с провайдером агента и выдаёт поток событий (только на добавление), который окно приложения отрисовывает как таймлайн. Ход — один обмен репликами в треде, от сообщения пользователя до конца ответа агента. Обычный тред выполняет работу сам, а тред-менеджер координирует другие треды.
Окружение — место, где работает тред: рабочий каталог, привязанный к одному хосту. Неуправляемое окружение указывает на существующий каталог. Управляемое (например, git worktree) создаётся специально для треда и удаляется, когда не остаётся неархивированных тредов, которые бы его использовали.
Хост — долгоживущий идентификатор демона конкретной машины. Собственная машина сервера — это primaryHostId. Машина — то, что выдаёт провайдер машины; как только её демон регистрируется, она становится видна как хост.
Эти объекты образуют словарь API плагинов. Провайдер окружения готовит рабочий каталог на хосте, событие жизненного цикла треда сообщает о завершённом или упавшем ходе, а панель в окне приложения узнаёт текущий проект и тред из useBbContext().
Собственные функции bb — это плагины
Заголовок раздела «Собственные функции bb — это плагины»Почти всё, что вы видите в окне приложения, и почти всё, что умеет агент, — это плагины. Они используют тот же публичный SDK, что и сторонние плагины. Провайдеры агентов для Claude Code, Codex, Pi и ACP-агентов — это плагины. Окружения git worktree, трекер задач, интеграция с GitHub и вопросы с вариантами ответов, которые агент задаёт в треде, — тоже плагины. В состав bb входят 36 плагинов из поставки bb и 9 плагинов-примеров, они перечислены в каталоге.
Проектные документы репозитория закрепляют базовое правило: ядро отвечает за минимум, и «every special case is a public primitive or is deleted». Ядро «never branches on a provider id».
Для автора плагинов отсюда следуют два вывода. Любая функция, которую вы видите в bb, доказывает, что плагин может сделать нечто подобное через API, который вы можете прочитать. А самый быстрый способ изучить API — открыть плагин из поставки bb, который его использует; страница Выбор поверхности сопоставляет идеи с такими плагинами.