@halcyonlabs/app weekly downloads statistics

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/e40bda56-54a4-47f8-a417-6bbadf2e5b40"> <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/4d9d02fb-c179-449b-a38a-041955143232"> <img alt="bb" src="https://github.com/user-attachments/assets/4d9d02fb-c179-449b-a38a-041955143232" width="128"> </picture> </p>

bb

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

This package provides the npx -y -p @halcyonlabs/app 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.19, 24, or 26.
• 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

<details> <summary>Windows via Ubuntu on WSL2</summary>

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.

Inside WSL2, use Linux paths rather than drive-letter or UNC 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.

</details>

Install and run

npx -y -p @halcyonlabs/app@latest bb-app

Then open: http://localhost:38886

To opt into the automated nightly channel:

npx -y -p @halcyonlabs/app@nightly bb-app

Nightly versions are built from main and may be unstable. The nightly dist-tag moves independently of the stable latest tag.

npm 12 and later block dependency install scripts by default. bb needs those scripts to build its native add-ons (better-sqlite3, node-pty, @parcel/watcher). Without them bb stops at startup with Could not locate the bindings file. If your npm version is 12 or later, allow the scripts for the install:

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

Or set the policy once for all global installs:

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

npx -y -p @halcyonlabs/app@latest bb-app downloads the published @halcyonlabs/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.

If another live bb owns the runtime record for the same data directory and a healthy server answers on the configured local address, startup exits with status 1 without starting either child process. The existing instance keeps running. A runtime record without a healthy server does not prevent startup.

Application logs rotate in logs/server.N.log and logs/host-daemon.N.log under the data directory, keeping the five newest files per service. Output that bypasses the logger, such as startup errors and crashes, goes directly to logs/server-stdio.log and logs/host-daemon-stdio.log. These files append across restarts; when one is over 10 MB as a service starts, it is renamed to -stdio.1.log, replacing the previous one. The launcher prints status and log locations without forwarding service output to the terminal, so a stalled terminal cannot block service logging. To follow everything with the default data directory:

tail -F ~/.bb/logs/*.log

Launcher status output is plain when stdout is redirected, including in CI. Set FORCE_COLOR=1 to request color or NO_COLOR=1 to disable it; NO_COLOR takes precedence. In-place progress updates require a stdout TTY.

The same output capture applies to bb-server and bb-host-daemon.

To stop a bb that runs in another terminal or in the background:

npx -y -p @halcyonlabs/app bb-app stop

stop reads bb-app-runtime.json from the data directory, confirms that the recorded process really is that launcher, then stops it. Pass --data-dir when the bb you want to stop does not use the default ~/.bb/.

The bb command

To control bb from outside bb, open Settings → General → Command line and choose Install next to bb CLI. Threads in bb already have bb; this is for your own terminals, scripts, and agents running outside bb, such as Claude Code or Codex. bb links a launcher from ~/.bb/bin/bb into a folder on your PATH (~/.local/bin on Linux; /opt/homebrew/bin, /usr/local/bin, or ~/.local/bin on macOS). On Windows it adds ~/.bb/bin to your user PATH; open a new terminal afterwards. Remove takes it off again. bb leaves any other bb you already have in place.

From a terminal, before bb is on your PATH:

npx -y -p @halcyonlabs/app bb settings cli-command install

Updating from the app…