https://github.com/ymichael/bb
bb is an agentic IDE that can control itself
https://github.com/ymichael/bb
Last synced: 6 days ago
JSON representation
bb is an agentic IDE that can control itself
- Host: GitHub
- URL: https://github.com/ymichael/bb
- Owner: ymichael
- License: mit
- Created: 2026-02-24T22:32:40.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-22T03:31:56.000Z (13 days ago)
- Last Synced: 2026-05-22T08:12:35.776Z (13 days ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/bb-app
- Size: 43.5 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# bb
[](https://www.npmjs.com/package/bb-app)
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.
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. 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](https://github.com/ymichael/bb/releases/tag/desktop-latest)**
The desktop build is currently macOS Apple Silicon (arm64) only. Intel Mac,
Linux, and Windows users should run bb with `npx` instead.
### Or run it anywhere with npx
```bash
npx bb-app@latest
```
Then open `http://localhost:38886`.
bb uses the provider CLI you already have authenticated.
For install requirements, provider setup, configuration, and package-focused
docs, start with
[`packages/bb-app`](./packages/bb-app/README.md).
## Repository Overview
This monorepo contains the packaged app plus the runtime services it bundles:
| Package or app | Role |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| [`packages/bb-app`](./packages/bb-app) | Published npm package and `npx bb-app@latest` launcher. |
| [`apps/app`](./apps/app) | Web UI for inspecting projects, threads, environments, and running work. |
| [`apps/server`](./apps/server) | HTTP API, WebSocket notifications, state management, and server-owned product policy. |
| [`apps/host-daemon`](./apps/host-daemon) | Host-local runtime that provisions workspaces and runs provider processes. |
| [`apps/cli`](./apps/cli) | Scriptable `bb` CLI for users and agents. |
| [`packages/server-contract`](./packages/server-contract) | HTTP and WebSocket contract between clients and the server. |
| [`packages/host-daemon-contract`](./packages/host-daemon-contract) | Command/event contract between the server and host daemons. |
## Development
Use the development loop when working on bb itself:
```bash
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//` 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.
Development behavior is intentionally split:
- the app hot reloads itself
- the server does not hot reload
- the host daemon does not hot reload
When you want the server and host daemon to pick up the latest build output, use:
```bash
pnpm dev:restart
pnpm dev:restart-server
pnpm dev:restart-host-daemon
```
These rebuild first, then restart only the targeted stateful services.
To test the release-style package launcher from a source checkout:
```bash
pnpm start
```
That builds the local `bb-app` package artifacts and runs
`packages/bb-app/dist/bb-app.js`, matching the published `npx bb-app@latest` path
without downloading from npm.
To test an additional host against that dev server, use:
```bash
BB_HOST_DAEMON_PORT=39999 pnpm dev:host-daemon -- --auto-join
```
That runs a second host daemon against the dev server and stores its state
under the current checkout's dev data directory. The extra daemon requires an
explicit unused `BB_HOST_DAEMON_PORT` so it does not collide with the primary
dev daemon. On first run, it requests local enrollment from the dev server;
after enrollment, the daemon persists its auth state locally.
```bash
pnpm bb --help # built CLI, targets the default/prod instance
pnpm reset # clear production state
pnpm bb:dev --help # source CLI, targets this checkout's dev instance
pnpm reset:dev # clear this checkout's dev state
pnpm reset:all # clear both production and dev states
```
These reset commands prompt for confirmation before deleting anything.
## System Overview
### The runtime pieces
| Component | Role |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Server** | Central hub. Stores all state in a SQLite database, exposes an HTTP API, and pushes change notifications over WebSocket. Stateless itself — the DB is the source of truth. Routes work to hosts by queuing commands. |
| **Host daemon** | Runs on each host (your laptop or a remote server). Connects to the server, picks up commands, provisions workspaces, runs agent provider processes, and streams events back. Exposes a local HTTP API for the app and CLI to do machine-local things (open editor, pick folders, check daemon status). |
| **App** | Web UI for inspecting projects and threads, following progress, and steering work. |
| **CLI** (`bb`) | First-class interface for both users and agents. Same capabilities as the app, scriptable. |
### Data model
The core entities and how they relate:
**Project** — the top-level container, usually mapped to a repository. A project has one or more **sources** that say where its code lives: local paths on specific hosts.
**Thread** — the unit of work. Each thread tracks a conversation with an agent provider, has lifecycle state, and produces an append-only stream of **events** (messages, tool calls, file changes, etc.). Threads can be **standard** (does work directly) or **manager** (coordinates other threads). Threads can own child threads for delegation.
**Environment** — the execution context for a thread. It binds a workspace (a directory on disk) to a host. An environment can be **unmanaged** (point at an existing directory), or **managed**. Environments managed by bb will be cleaned up when there are no longer any unarchived threads using it. Multiple threads can share an environment.
**Host** — a long-lived machine that runs a daemon, such as your laptop or a remote server.
**Commands and events** — the server talks to daemons by queuing commands (provision an environment, start a thread, stop a thread). Daemons report back by posting events. This is an asynchronous command/event protocol — the server queues work, the daemon picks it up, results flow back as events.
### Contracts and boundaries
Two contract packages define the boundaries between components:
**`@bb/server-contract`** — the HTTP + WebSocket API between clients (app, CLI) and the server. Route schemas, request/response types, WebSocket notification types.
**`@bb/host-daemon-contract`** — the protocol between the server and host daemons. Command types, event types, session lifecycle, the local API for app/CLI.
Implementation packages never import across these boundaries. The server doesn't know how workspaces are provisioned. The daemon doesn't know about threads or projects beyond what commands tell it.
## Further Reading
- [Vision](docs/VISION.md)
- [Platform support](docs/platform-support.md)
- [Configuration](docs/configuration.md)
- [Using bb on multiple devices](docs/multiple-devices.md)
- [Adding another host](docs/additional-hosts.md)
- [Worktrees and setup scripts](docs/worktrees.md)
## Contributing
The most useful contributions are feature requests and bug reports. If you run into something broken, confusing, or missing, open an issue with the workflow you were trying to accomplish and what happened instead.