bb

bb is an agentic IDE that builds itself. It can control, customize, and automate itself, laying the groundwork for your own software factory.

Every surface — the desktop app, web app, CLI, and HTTP API — is a first-class way to drive bb. Work runs in threads you can follow live, steer at any point, or hand off to another agent.

[!NOTE] bb is in active development. Core architecture is stable, but workflows and surfaces are still evolving.

Use bb

Download the desktop app

The recommended way to start using bb is the desktop app:

Download the latest desktop app

The desktop app supports macOS on Apple Silicon (arm64). The Linux x64 AppImage and the Windows x64 installer are alpha: expect problems, and please report them. Intel Mac users should run bb with npx instead. Native Windows needs Git for Windows, which bb uses for Git and for environment setup scripts. You can also run bb inside WSL2 (Windows Subsystem for Linux): install WSL2 first, then run the npx command below from your WSL2 (Linux) shell.

Early adopters can install bb Nightly alongside the stable desktop app. It has a separate application identity, yellow icon, and auto-update feed.

Or run it anywhere with npx

npx bb-app@latest

Then open http://localhost:38886.

To control bb from outside bb with the bb CLI, open Settings → General → Command line and choose Install. See The bb Command On PATH.

To run the newest automated build instead:

npx bb-app@nightly

npm 12 and later block dependency install scripts by default. bb needs those scripts to build its native add-ons. If your npm version is 12 or later, allow the scripts for the install:

npx --allow-scripts=better-sqlite3,node-pty,@parcel/watcher bb-app@latest

Or set the policy once for all global installs:

npm config set allow-scripts=better-sqlite3,node-pty,@parcel/watcher --location=user

bb uses the provider CLI you already have authenticated.

For install requirements, provider setup, configuration, and package-focused docs, start with packages/bb-app.

Telemetry

Production runs (the desktop app, npx bb-app, and pnpm start checkouts) send anonymous usage telemetry (app starts, thread creation counts, user message counts, and plugin installs) to help us understand adoption. Each event carries the app version, how bb was installed (desktop, npm, or source checkout), and the OS release, CPU architecture, and Node version. Source checkouts report whether origin points to github.com/get-bb/bb, another repository, or is unavailable. Telemetry never includes Git commit hashes or remote URLs. Identification is a random per-install id stored in your data dir — no user, host, project, workspace, or message content is ever attached. Plugin install events name only public plugins (bundled plugins and bb-community marketplace entries); installs from a local path, a private git or npm source, or a third-party marketplace report no name. Development runs (pnpm dev, pnpm start:worktree) never send. Opt out any run with BB_TELEMETRY=false. See apps/server/src/services/system/telemetry.ts.

Development

Use the development loop when working on bb itself:

pnpm dev

That starts the Vite app and proxies API and WebSocket traffic to a separate dev server. The launcher prints the actual ports at startup. Each checkout gets a data directory under ~/.bb-dev/<checkout-instance>/ and deterministic high ports derived from the checkout path. The checkout instance id is the sanitized path to the checkout, relative to your home directory, plus a short hash suffix. Separate worktrees can run alongside each other and the packaged npx bb-app@latest instance.

To test the production bundle and serving path without switching to production data or ports, use:

pnpm start:worktree

This builds the same optimized frontend and runtime artifacts as pnpm start, then serves the app from the BB server on the checkout-specific dev server port. It keeps the normal checkout-specific dev data directory and host-daemon port. There is no Vite dev server or hot reload in this mode; rerun the command after source changes. As with pnpm dev, worktree starts do not send telemetry.

For the Electron desktop shell, keep pnpm dev running and start the desktop package in a second terminal:

pnpm exec turbo run dev --filter=@bb/desktop

The desktop shell connects to this checkout's running dev app. Stop each command with Ctrl-C in its terminal.

To use the dev app from another machine over Tailscale, start it with the Tailscale browser origin configured:

BB_APP_URL=https://<machine>.<tailnet>.ts.net pnpm dev

Note the printed app port, then publish the loopback Vite listener in another terminal:

tailscale serve --bg --https=443 http://127.0.0.1:<app-port>

Then open https://<machine>.<tailnet>.ts.net. Source dev binds both the Vite app and main server to loopback by default; Vite continues to proxy API and WebSocket traffic.

For direct access at http://<tailscale-ip>:<app-port> instead, run:

pnpm dev:remote

This is the beginning of the README. Read the rest at the original. Read the full README ↗