bb

bb is an agentic IDE that can control itself. You can seamlessly orchestrate all of your favorite coding agents together and have them programmatically use bb too.

This package provides the npx bb-app launcher, bundled bb CLI entry, and Node SDK export. Every surface — the 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. Workflows and surfaces are still evolving.

Quick Start

bb runs from npm and orchestrates coding agents you already have installed.

Prerequisites

• Node.js 22 LTS or newer. Node 20.19.x is best-effort only.
• Git.
• At least one supported agent provider: Claude Code, Codex, Cursor via ACP, Pi, or another ACP-compatible agent.

If you already use one of these providers, bb will pick up your existing credentials. If you use multiple providers, you can mix and match per task.

Supported host environments

• macOS
• Linux

Run all bb commands inside WSL2, install Node.js, Git, and your provider CLIs inside that WSL2 distro, and use Linux-style paths such as /home/me/repo or /mnt/c/Users/me/repo.

Native Windows PowerShell, CMD, drive-letter paths, and UNC paths are not supported product paths. Repos inside the WSL filesystem are recommended; /mnt/c/... is intentionally supported so you can keep an existing Windows checkout, but it is slower and less reliable for file watching.

Install and run

npx bb-app@latest

Then open: http://localhost:38886

npx bb-app@latest downloads the published bb-app package, starts the server and local host daemon, and serves the web app. It stores bb-managed state under ~/.bb/ by default. If either managed child process exits unexpectedly, the launcher restarts that child without stopping the other one. Press Ctrl+C in the terminal to stop both processes and exit with status 0.

From the app, add or open a project, start a thread, and choose the provider you want that thread to use.

CLI

The package also exposes the bb CLI for an already-running bb server:

npx --package bb-app bb --help

The CLI uses the same BB_SERVER_URL and bb config resolution as the SDK. When unset, it targets the default local packaged server at http://127.0.0.1:38886.

Scripting with the SDK

The package also exposes a Node SDK for scripts that drive an already-running bb server:

import { BBSdk } from "bb-app";

const bb = new BBSdk();
const thread = await bb.threads.spawn({
  projectId: "proj_personal",
  environment: { type: "host", workspace: { type: "personal" } },
  prompt: "Summarize my active bb work.",
});
await bb.threads.wait({ threadId: String(thread.id), status: "idle" });
console.log(await bb.threads.output({ threadId: String(thread.id) }));

new BBSdk() uses the same BB_SERVER_URL and bb config resolution as the CLI. Pass new BBSdk({ baseUrl: "http://host:38886" }) for remote or test targets. Scripts launched by bb already receive BB_SERVER_URL and BB_THREAD_ID in their environment.

Provider Credentials

bb uses whichever providers you have configured. Common providers:

| Provider | Setup | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | codex | Install the Codex CLI. Then run codex login or configure credentials per the Codex docs. | | claude-code | Install Claude Code and authenticate per its docs. | | cursor | Install Cursor's agent CLI (agent) and authenticate per Cursor's docs. | | pi | See the Pi coding agent docs. Run pi and then /login for interactive setup. | | opencode | Install opencode and authenticate per its docs. | | grok | Install Grok Build and authenticate with grok login or XAI_API_KEY. | | hermes-agent | Install Hermes Agent, configure credentials with hermes model, then verify ACP with hermes acp --check. |

Custom ACP agents can be configured through customAcpAgents in ~/.bb/config.json; see the configuration docs for optional modelCli and reasoningCli or nativeReasoning reasoning settings. A logo field accepts an SVG, PNG, or WebP path for the provider picker icon.

Configuration

Use bb-app config for persistent non-secret package settings under ~/.bb/config.json:

npx bb-app config set BB_APP_URL http://<machine>.<tailnet>.ts.net:38886
npx bb-app config set BB_INFERENCE codex/gpt-5.4-mini
npx bb-app config set BB_TRANSCRIPTION codex/gpt-4o-mini-transcribe
npx bb-app config list
npx bb-app config refresh

Use bb-app client ssh-target to configure local editor opens for remote bb servers under ~/.bb/client.json. The target is the value that works after ssh, such as devbox or user@devbox:

npx bb-app client ssh-target set https://bb.example.test devbox
npx bb-app client ssh-target list

Use bb-app env for provider credentials under ~/.bb/env.json:

npx bb-app env set OPENAI_API_KEY <key>
npx bb-app env list
npx bb-app env unset OPENAI_API_KEY

env list redacts all values. Config and env writes ask a running local bb server to reload; if bb is stopped, the values apply on the next start.

For all config keys, precedence, startup flags, and source-development .env behavior, see the configuration docs.

Further Reading

• Main README
• Platform support
• Configuration
• Using bb on multiple devices
• Worktrees and setup scripts