get-bb/bb

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.