# get-bb/bb architecture

> Architecture diagram of the GitHub repository get-bb/bb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/get-bb/bb
- Repository: https://github.com/get-bb/bb

## Overview

#### Purpose and entry points
bb is a TypeScript monorepo for an agentic IDE: coding-agent work executes in live, steerable threads across desktop, browser, CLI, HTTP API, and plugins. Main launch paths are the distributable launcher in `packages/bb-app/src/launcher.ts`, CLI entry in `apps/cli/src/index.ts`, server startup in `apps/server/src/start-server.ts`, desktop Electron main process in `apps/desktop/src/main.ts`, and React app bootstrap in `apps/app/src/main.tsx`.

#### Client surfaces
The primary UI is a Vite/React application with routing, layouts, thread views, prompt composition, timeline rendering, and local query/realtime state. `apps/app/src/App.tsx` composes the application; `apps/app/src/views/thread-detail/ThreadDetailView.tsx` is the core thread workspace; `apps/app/src/hooks/queries/thread-queries.ts` and `apps/app/src/hooks/realtime-cache-effects.ts` bridge server state into the client cache. The CLI is a peer control surface, organized by resource commands in `apps/cli/src/commands/thread/index.ts` and using `apps/cli/src/client.ts`.

#### Server: system-of-record and orchestration
The Node server exposes typed HTTP routes and WebSocket protocols, owns durable state, and coordinates thread/environment lifecycles. Its assembly points are `apps/server/src/server.ts` and `apps/server/src/index.ts`; public resource boundaries are in `apps/server/src/routes/threads/index.ts`, `apps/server/src/routes/environments.ts`, and `apps/server/src/routes/hosts.ts`. Thread creation, execution planning, dispatch, event persistence, and timeline pagination are concentrated in `apps/server/src/services/threads/thread-create.ts`, `apps/server/src/services/threads/thread-turn-dispatch.ts`, and `apps/server/src/services/threads/timeline.ts`.

#### Agent execution and host boundary
Agent processes do not run in the browser-facing server directly. The host daemon runs on a machine with workspaces and provider CLIs, exposes local commands/files/terminals, manages runtime processes, and connects back to the server. Key boundaries are `apps/host-daemon/src/daemon.ts`, `apps/host-daemon/src/command-router.ts`, `apps/host-daemon/src/runtime-manager.ts`, and `apps/host-daemon/src/server-connection.ts`. Workspace provisioning and Git worktrees are host-local concerns in `packages/host-workspace/src/provisioning.ts` and `packages/host-workspace/src/workspace.ts`.

#### Provider normalization and thread event flow
`packages/agent-runtime/src/runtime.ts` supervises provider processes and normalizes their lifecycle, tool calls, permission/interactive requests, and events. Provider adapters cover ACP, Claude Code, Codex, and Pi in `packages/agent-runtime/src/acp/adapter.ts`, `packages/agent-runtime/src/claude-code/adapter.ts`, and `packages/agent-runtime/src/codex/adapter.ts`. The server receives host/runtime events through `apps/server/src/ws/daemon-protocol.ts` and fan-outs client updates via `apps/server/src/ws/hub.ts`; persistent events are projected into client timeline rows by `packages/thread-view/src/build-thread-timeline.ts`.

#### Persistence, contracts, and realtime
SQLite is the local system-of-record, accessed through `packages/db/src/connection.ts`, schema/data modules such as `packages/db/src/schema.ts` and `packages/db/src/data/events.ts`, and migrations under `packages/db/drizzle/`. Shared HTTP/API payload definitions reside in `packages/server-contract/src/api-types.ts`; host-daemon RPC contracts in `packages/host-daemon-contract/src/commands.ts`; client SDK transport/realtime APIs in `packages/sdk/src/core.ts` and `packages/sdk/src/realtime-client.ts`. These packages are deliberate compatibility boundaries between surfaces and runtimes.

#### Extensibility, desktop, and remote connectivity
Plugins can contribute server behavior, agent capabilities, CLI commands, skills, and React UI slots. The server lifecycle is in `apps/server/src/services/plugins/plugin-service.ts` and `apps/server/src/services/plugins/plugin-runtime.ts`; frontend hosting is in `apps/app/src/lib/plugin-sdk-app-impl.tsx`; the public author contract is `packages/plugin-sdk/src/index.ts`. Electron wraps the app, supervises local/foreign server targets, native browser views, and updates through `apps/desktop/src/owned-runtime-supervisor.ts` and `apps/desktop/src/desktop-browser-view.ts`. Optional multi-device connectivity uses a Cloudflare Worker tunnel (`apps/connect/src/worker.ts`, `apps/connect/src/tunnel-do.ts`), with enrollment/session support in `packages/connect-client/src/desktop-session.ts`.

Main entry points: [`apps/server/src/server.ts`](https://github.com/get-bb/bb/blob/main/apps/server/src/server.ts) (Typed HTTP and WebSocket server), [`packages/sdk/src/realtime-client.ts`](https://github.com/get-bb/bb/blob/main/packages/sdk/src/realtime-client.ts) (Client SDK and realtime), [`apps/desktop/src/main.ts`](https://github.com/get-bb/bb/blob/main/apps/desktop/src/main.ts) (Electron desktop), [`apps/server/src/services/threads/thread-turn-dispatch.ts`](https://github.com/get-bb/bb/blob/main/apps/server/src/services/threads/thread-turn-dispatch.ts) (Thread orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_launcher{{"Distributable launcher<br/>[launcher.ts]"}}
  node_web_app["React thread workspace<br/>Vite React app<br/>[App.tsx]"]
  node_thread_detail["Thread detail view<br/>workspace view"]
  node_cli["CLI thread commands<br/>[index.ts]"]
  node_desktop["Electron desktop<br/>Electron main<br/>[main.ts]"]
end

subgraph group_server["Server control plane"]
  node_server_app["Typed HTTP and WebSocket server<br/>Node server<br/>[server.ts]"]
  node_thread_orchestration["Thread orchestration<br/>thread service"]
  node_daemon_protocol["Daemon event protocol<br/>WebSocket protocol<br/>[daemon-protocol.ts]"]
  node_realtime_hub["Client realtime hub<br/>WebSocket fan-out<br/>[hub.ts]"]
end

subgraph group_host["Host execution"]
  node_host_daemon["Host daemon<br/>machine agent<br/>[daemon.ts]"]
  node_runtime_manager["Runtime manager<br/>process manager<br/>[runtime-manager.ts]"]
  node_workspace["Workspace provisioning<br/>host workspace<br/>[provisioning.ts]"]
  node_agent_runtime["Agent runtime<br/>provider supervisor<br/>[runtime.ts]"]
  node_provider_adapters["Provider adapters<br/>[adapter.ts]"]
end

subgraph group_shared["Shared contracts &amp; state"]
  node_database[("SQLite durable state<br/>[connection.ts]")]
  node_timeline_projection["Timeline projection<br/>event projection"]
  node_api_contract["HTTP API contract<br/>shared types<br/>[api-types.ts]"]
  node_sdk["Client SDK and realtime<br/>client transport<br/>[realtime-client.ts]"]
end

subgraph group_extension["Extension &amp; connectivity"]
  node_plugin_runtime["Plugin runtime<br/>server extension host<br/>[plugin-runtime.ts]"]
  node_plugin_sdk["Plugin SDK<br/>author contract<br/>[index.ts]"]
  node_connect_tunnel["Remote tunnel<br/>Cloudflare Worker<br/>[worker.ts]"]
end

node_launcher -->|"launches"| node_desktop
node_desktop -->|"hosts"| node_web_app
node_desktop -->|"supervises"| node_server_app
node_web_app -->|"renders"| node_thread_detail
node_thread_detail -->|"uses"| node_sdk
node_cli -->|"uses"| node_api_contract
node_sdk -->|"implements"| node_api_contract
node_sdk -->|"HTTP and realtime"| node_server_app
node_api_contract -.->|"defines boundary"| node_server_app
node_server_app -->|"routes turns"| node_thread_orchestration
node_thread_orchestration -->|"persists state and events"| node_database
node_database -->|"supplies events"| node_timeline_projection
node_timeline_projection -->|"timeline rows"| node_thread_detail
node_thread_orchestration -->|"dispatches execution"| node_host_daemon
node_host_daemon -->|"manages"| node_runtime_manager
node_host_daemon -->|"provisions"| node_workspace
node_runtime_manager -->|"runs"| node_agent_runtime
node_agent_runtime -->|"normalizes providers"| node_provider_adapters
node_agent_runtime -->|"emits events via host"| node_daemon_protocol
node_daemon_protocol -->|"persists events"| node_database
node_daemon_protocol -->|"publishes updates"| node_realtime_hub
node_realtime_hub -->|"fan-out"| node_sdk
node_plugin_sdk -.->|"implemented by plugins"| node_plugin_runtime
node_plugin_runtime -->|"extends lifecycle"| node_server_app
node_connect_tunnel -->|"remote access"| node_server_app

click node_launcher "https://github.com/get-bb/bb/blob/main/packages/bb-app/src/launcher.ts"
click node_web_app "https://github.com/get-bb/bb/blob/main/apps/app/src/App.tsx"
click node_thread_detail "https://github.com/get-bb/bb/blob/main/apps/app/src/views/thread-detail/ThreadDetailView.tsx"
click node_cli "https://github.com/get-bb/bb/blob/main/apps/cli/src/commands/thread/index.ts"
click node_desktop "https://github.com/get-bb/bb/blob/main/apps/desktop/src/main.ts"
click node_server_app "https://github.com/get-bb/bb/blob/main/apps/server/src/server.ts"
click node_thread_orchestration "https://github.com/get-bb/bb/blob/main/apps/server/src/services/threads/thread-turn-dispatch.ts"
click node_daemon_protocol "https://github.com/get-bb/bb/blob/main/apps/server/src/ws/daemon-protocol.ts"
click node_realtime_hub "https://github.com/get-bb/bb/blob/main/apps/server/src/ws/hub.ts"
click node_database "https://github.com/get-bb/bb/blob/main/packages/db/src/connection.ts"
click node_timeline_projection "https://github.com/get-bb/bb/blob/main/packages/thread-view/src/build-thread-timeline.ts"
click node_api_contract "https://github.com/get-bb/bb/blob/main/packages/server-contract/src/api-types.ts"
click node_sdk "https://github.com/get-bb/bb/blob/main/packages/sdk/src/realtime-client.ts"
click node_host_daemon "https://github.com/get-bb/bb/blob/main/apps/host-daemon/src/daemon.ts"
click node_runtime_manager "https://github.com/get-bb/bb/blob/main/apps/host-daemon/src/runtime-manager.ts"
click node_workspace "https://github.com/get-bb/bb/blob/main/packages/host-workspace/src/provisioning.ts"
click node_agent_runtime "https://github.com/get-bb/bb/blob/main/packages/agent-runtime/src/runtime.ts"
click node_provider_adapters "https://github.com/get-bb/bb/blob/main/packages/agent-runtime/src/acp/adapter.ts"
click node_plugin_runtime "https://github.com/get-bb/bb/blob/main/apps/server/src/services/plugins/plugin-runtime.ts"
click node_plugin_sdk "https://github.com/get-bb/bb/blob/main/packages/plugin-sdk/src/index.ts"
click node_connect_tunnel "https://github.com/get-bb/bb/blob/main/apps/connect/src/worker.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_web_app,node_thread_detail,node_cli,node_desktop toneBlue
class node_server_app,node_thread_orchestration,node_daemon_protocol,node_realtime_hub toneAmber
class node_host_daemon,node_runtime_manager,node_workspace,node_agent_runtime,node_provider_adapters toneMint
class node_database,node_timeline_projection,node_api_contract,node_sdk toneRose
class node_plugin_runtime,node_plugin_sdk,node_connect_tunnel toneIndigo
```

## Components

### User surfaces

- [Distributable launcher](https://github.com/get-bb/bb/blob/main/packages/bb-app/src/launcher.ts): launcher · `packages/bb-app/src/launcher.ts`
- [React thread workspace](https://github.com/get-bb/bb/blob/main/apps/app/src/App.tsx): Vite React app · Thread UI, prompts, timeline, and realtime cache. · `apps/app/src/App.tsx`
- [Thread detail view](https://github.com/get-bb/bb/blob/main/apps/app/src/views/thread-detail/ThreadDetailView.tsx): workspace view · `apps/app/src/views/thread-detail/ThreadDetailView.tsx`
- [CLI thread commands](https://github.com/get-bb/bb/blob/main/apps/cli/src/commands/thread/index.ts): CLI · `apps/cli/src/commands/thread/index.ts`
- [Electron desktop](https://github.com/get-bb/bb/blob/main/apps/desktop/src/main.ts): Electron main · Supervises server targets and native browser views. · `apps/desktop/src/main.ts`

### Server control plane

- [Typed HTTP and WebSocket server](https://github.com/get-bb/bb/blob/main/apps/server/src/server.ts): Node server · System of record and lifecycle coordinator. · `apps/server/src/server.ts`
- [Thread orchestration](https://github.com/get-bb/bb/blob/main/apps/server/src/services/threads/thread-turn-dispatch.ts): thread service · Creates turns, plans execution, dispatches work, and pages timelines. · `apps/server/src/services/threads/thread-turn-dispatch.ts`
- [Daemon event protocol](https://github.com/get-bb/bb/blob/main/apps/server/src/ws/daemon-protocol.ts): WebSocket protocol · `apps/server/src/ws/daemon-protocol.ts`
- [Client realtime hub](https://github.com/get-bb/bb/blob/main/apps/server/src/ws/hub.ts): WebSocket fan-out · `apps/server/src/ws/hub.ts`

### Host execution

- [Host daemon](https://github.com/get-bb/bb/blob/main/apps/host-daemon/src/daemon.ts): machine agent · Machine-local boundary for workspaces, commands, terminals, and runtimes. · `apps/host-daemon/src/daemon.ts`
- [Runtime manager](https://github.com/get-bb/bb/blob/main/apps/host-daemon/src/runtime-manager.ts): process manager · `apps/host-daemon/src/runtime-manager.ts`
- [Workspace provisioning](https://github.com/get-bb/bb/blob/main/packages/host-workspace/src/provisioning.ts): host workspace · Provisions workspaces and Git worktrees locally. · `packages/host-workspace/src/provisioning.ts`
- [Agent runtime](https://github.com/get-bb/bb/blob/main/packages/agent-runtime/src/runtime.ts): provider supervisor · Normalizes provider lifecycle, tools, permissions, and events. · `packages/agent-runtime/src/runtime.ts`
- [Provider adapters](https://github.com/get-bb/bb/blob/main/packages/agent-runtime/src/acp/adapter.ts): ACP / Claude / Codex · `packages/agent-runtime/src/acp/adapter.ts`

### Shared contracts & state

- [SQLite durable state](https://github.com/get-bb/bb/blob/main/packages/db/src/connection.ts): SQLite · Threads, environments, hosts, and persisted events. · `packages/db/src/connection.ts`
- [Timeline projection](https://github.com/get-bb/bb/blob/main/packages/thread-view/src/build-thread-timeline.ts): event projection · `packages/thread-view/src/build-thread-timeline.ts`
- [HTTP API contract](https://github.com/get-bb/bb/blob/main/packages/server-contract/src/api-types.ts): shared types · `packages/server-contract/src/api-types.ts`
- [Client SDK and realtime](https://github.com/get-bb/bb/blob/main/packages/sdk/src/realtime-client.ts): client transport · `packages/sdk/src/realtime-client.ts`

### Extension & connectivity

- [Plugin runtime](https://github.com/get-bb/bb/blob/main/apps/server/src/services/plugins/plugin-runtime.ts): server extension host · Loads server behavior and agent capabilities. · `apps/server/src/services/plugins/plugin-runtime.ts`
- [Plugin SDK](https://github.com/get-bb/bb/blob/main/packages/plugin-sdk/src/index.ts): author contract · `packages/plugin-sdk/src/index.ts`
- [Remote tunnel](https://github.com/get-bb/bb/blob/main/apps/connect/src/worker.ts): Cloudflare Worker · Optional multi-device connectivity. · `apps/connect/src/worker.ts`

## Connections

- Distributable launcher → Electron desktop: launches
- Electron desktop → React thread workspace: hosts
- Electron desktop → Typed HTTP and WebSocket server: supervises
- React thread workspace → Thread detail view: renders
- Thread detail view → Client SDK and realtime: uses
- CLI thread commands → HTTP API contract: uses
- Client SDK and realtime → HTTP API contract: implements
- Client SDK and realtime → Typed HTTP and WebSocket server: HTTP and realtime
- HTTP API contract → Typed HTTP and WebSocket server: defines boundary
- Typed HTTP and WebSocket server → Thread orchestration: routes turns
- Thread orchestration → SQLite durable state: persists state and events
- SQLite durable state → Timeline projection: supplies events
- Timeline projection → Thread detail view: timeline rows
- Thread orchestration → Host daemon: dispatches execution
- Host daemon → Runtime manager: manages
- Host daemon → Workspace provisioning: provisions
- Runtime manager → Agent runtime: runs
- Agent runtime → Provider adapters: normalizes providers
- Agent runtime → Daemon event protocol: emits events via host
- Daemon event protocol → SQLite durable state: persists events
- Daemon event protocol → Client realtime hub: publishes updates
- Client realtime hub → Client SDK and realtime: fan-out
- Plugin SDK → Plugin runtime: implemented by plugins
- Plugin runtime → Typed HTTP and WebSocket server: extends lifecycle
- Remote tunnel → Typed HTTP and WebSocket server: remote access