bb Architecture Research Notes
Research notes from reading the get-bb/bb repository (SHA 3e3e1934) and examining the locally installed bb 0.35.1 app. bb is an agent orchestrator and normalizer — it doesn't call Anthropic or OpenAI APIs itself. Instead, it shells out to existing agent harnesses (Codex CLI, Claude Code via the Claude Agent SDK, Pi SDK, ACP agents including Cursor) and normalizes their traffic into a shared bb thread-event model.
Architecture
The request path flows through four layers: Server (apps/server, SQLite-backed source of truth for threads and policy) → Host Daemon (WebSocket RPC, provisions workspaces and spawns provider processes) → Agent Runtime (packages/agent-runtime, JSON-RPC framing, never interprets provider-specific content) → Provider Adapter (builds command plans and translates events for each provider).
Two adapter shapes are supported. In-process protocol adapters are for providers with stable JSON-RPC wire protocols (Codex app-server). Bridge-process adapters spawn Node bridges (bb-*-bridge.mjs) that host an SDK or ACP client and expose bb's common JSON-RPC surface on stdio.
Supported Providers
| Provider | Shape | What runs |
|---|---|---|
| Codex | Direct JSON-RPC | codex app-server per thread |
| Claude Code | Bridge | node bb-claude-code-bridge.mjs → Claude Agent SDK → claude CLI |
| Pi | Bridge | node bb-pi-bridge.mjs → Pi coding-agent SDK |
| Cursor | Bridge + ACP | node bb-acp-bridge.mjs → agent acp |
| opencode, omp, Grok Build, Hermes | Known ACP | Direct acp invocation |
Process Lifecycle
Codex processes are thread-scoped (one codex app-server per bb thread). Claude Code, Pi, and ACP bridges are provider-scoped (one bridge process hosts multiple bb threads; ACP still spawns one agent child per thread). Maintenance probes (model lists) can use a provider-scoped Codex process without a thread.
Claude Code Integration
The Claude bridge forwards raw Claude Agent SDK messages as { method: "sdk/message" }, leaving the parent adapter to translate SDKMessage → ThreadEvent[]. The SDK's query() is called with an async iterable of user messages (not one-shot CLI argv), pointed at the host claude executable. Skills are injected as local plugins, dynamic bb tools are exposed as an in-process MCP server named bb-bridge, and interactive permissions are bridged back to bb as pending interactions.
ACP Integration
bb implements a minimal ACP client (no external ACP SDK) with NDJSON frames over stdio. The initialize → authenticate → session/new → session/prompt → session/update flow mirrors the standard ACP lifecycle. Model/reasoning for Cursor-style agents is encoded in model ID variants selected at launch (--model ...).
Design Philosophy
bb is explicitly not a thin chat client. It's an orchestrator (projects, environments/worktrees, parent/child threads, permissions UX, skills/plugins) and a normalizer (each harness keeps its own session identity and tooling; bb adapts them into one timeline and one CLI/API). It explicitly rejected a shared bridge skeleton — Claude and Pi bridges remain separate, and ACP support is a subset of the protocol sufficient for session/prompt/tools/permissions/fs in practice.