Search docs

Jump to a BRB documentation page

BRB DocsContinuity infrastructure for AI-built software
npmOpen BRB
Getting started

Set up BRB and connect a repo in minutes

Install the published brbgit package, sign in, register a repo, and move straight into watch mode or the daemon.

Introduction
https://docs.brbgit.com/getting-started

Install the CLI

bash
npm install -g brbgit
brb help
Package vs command

The npm package is brbgit. The installed command is brb.

Hosted by default

The CLI defaults to https://app.brbgit.com. Use --base-url only when you want to point at a local or non-production BRB service.

Sign in first

BRB is private by default. Sign in once in the CLI, and every repo you create or sync belongs only to that account.

bash
brb login
Create the account if needed

Use brb login --register when you need to create the account and save the CLI token in one step.

Requirements

  • Node.js 20 or newer.
  • A real local git repository.
  • Access to the hosted BRB service.
  • A BRB account for private repo access.
  • Codex session logs under ~/.codex/sessions if you want conversation sync.

Register a repo

BRB keeps a local registry at ~/.brb/registry.json. Registering a repo creates the remote repo agent if it does not already exist and stores the local-to-remote mapping.

If you do not pass --repo, BRB suggests the local package.json name when one exists and falls back to the git root directory name.

bash
cd /absolute/path/to/my-project
brb init

Start syncing

bash
cd /absolute/path/to/my-project
brb watch
Agent-first shortcut on macOS
cd /absolute/path/to/my-project
brb sync --ensure-daemon
  1. 1The first watch session performs a startup sync automatically.
  2. 2brb sync --ensure-daemon can register repo, run immediate sync, and start background syncing in one step.
  3. 3BRB compares the local working tree with the last synced manifest.
  4. 4Only the changed files and deletions are sent to the remote repo agent.
  5. 5The repo agent writes the new state, records continuity, and creates a remote commit.
Manual sync is optional

Use brb sync when you want an immediate one-off sync. You do not need it before watch mode or the daemon.

Move to background sync

  • Use watch while testing one repo interactively.
  • Use the macOS daemon to watch every registered repo automatically at login.
  • The UI will then show sync state, recent activity, resume context, commits, and restore points.
Install the daemon instead of running watch manually
brb daemon install
launchctl load -w ~/Library/LaunchAgents/com.brb.daemon.plist

Optionally enable Cloudflare Artifacts

BRB uses Cloudflare Artifacts as the Git-native source of truth for code and history. BRB stays the continuity and auth layer while Artifacts stores the canonical history and file trees.

  1. 1Open the repo in the BRB app.
  2. 2Go to the Backup section.
  3. 3Confirm Artifacts is provisioned for the repo.
  4. 4Retry the canonical sync from the UI if you need to force a fresh push.
  5. 5Create an isolated session fork when you want separate agent work.
Cloudflare Worker secret for app.brbgit.com
cd apps/web
pnpm wrangler secret put ARTIFACTS_API_TOKEN
  • Artifacts is optional and uses the Artifacts REST API plus repo-scoped Git tokens in this rollout.
  • For local development, copy apps/web/.dev.vars.example to apps/web/.dev.vars and fill in ARTIFACTS_API_TOKEN.

Privacy model

Private repos only

BRB currently supports one authenticated owner per repo. Repo sharing is not available yet.

Next
How BRB works