brbgit

brbgit is the npm package for the BRB CLI.

It connects a local git repo to the BRB service, syncs file changes, watches for edits, and can keep registered repos syncing in the background on macOS.

The package name is brbgit, but the command you run is:

brb

Install

npm install -g brbgit

Then confirm it is available:

brb help

What It Does

• Registers a local git repo with the BRB service
• Syncs working-tree changes to the remote repo agent
• Generates remote commits automatically after edit bursts
• Watches local repos for changes and keeps them in sync
• Runs as a macOS launchd daemon for background syncing

Quick Start

Start from a real local git repo:

cd ~/github/sample
git status

Register the repo with BRB:

cd ~/github/sample
brb init

Push the current state:

brb sync

This is optional. If you start brb watch or the daemon after brb init, BRB runs an automatic startup sync for that registered repo.

Start watching for changes:

brb watch

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.

Commands

brb init

Registers the current repo, or a repo at --source, with the BRB service. If you do not pass --repo, BRB suggests the local package.json name when available and falls back to the git root directory name.

brb init [--repo <name>] [--source <path>] [--base-url <url>]

Example:

cd ~/github/sample
brb init

brb sync

Runs a one-off sync for a registered repo. You only need this when you want an immediate manual sync. brb watch and brb daemon already perform a startup sync automatically.

brb sync [--source <path>] [--message <message>] [--base-url <url>]

Example:

cd ~/github/sample
brb sync

brb watch

Watches a registered repo and syncs changes after a quiet period.

brb watch [--source <path>] [--quiet-window-ms <ms>] [--max-batch-window-ms <ms>] [--min-resync-gap-ms <ms>] [--base-url <url>]

Example:

brb watch \
  --quiet-window-ms 5000 \
  --max-batch-window-ms 30000 \
  --min-resync-gap-ms 2000

brb daemon run

Starts the background watcher process for every repo in the local registry.

brb daemon run [--base-url <url>] [--quiet-window-ms <ms>] [--max-batch-window-ms <ms>] [--min-resync-gap-ms <ms>]

brb daemon install

Installs a macOS launchd agent that starts BRB on login and watches every registered repo.

brb daemon install [--base-url <url>] [--quiet-window-ms <ms>] [--max-batch-window-ms <ms>] [--min-resync-gap-ms <ms>]

Load it with:

launchctl load -w ~/Library/LaunchAgents/com.brb.daemon.plist

brb daemon uninstall

Removes the macOS launchd agent file.

brb daemon uninstall

If it is currently loaded, unload it first:

launchctl unload -w ~/Library/LaunchAgents/com.brb.daemon.plist

brb repo create

Creates a repo on the remote BRB service.

brb repo create --name <name> [--base-url <url>]

brb push

Pushes a local repo to a named remote repo in one command.

brb push --repo <name> [--source <path>] [--message <message>] [--base-url <url>]

Sync Timing

brb watch and brb daemon use three timing controls:

• --quiet-window-ms Sync after no changes for this long
• --max-batch-window-ms Force a sync if changes keep happening for too long
• --min-resync-gap-ms Prevent immediate back-to-back syncs

Default values:

quiet-window-ms: 5000
max-batch-window-ms: 30000
min-resync-gap-ms: 2000

Environment Variables

brb reads:

• BRB_BASE_URL
• GIT_AGENT_BASE_URL as a legacy fallback

If no URL is provided, the CLI defaults to https://app.brbgit.com.

Local State

Current state directory:

~/.brb

This includes:

• repo registry
• sync manifests
• daemon logs

Legacy ~/.git-agent state is still read automatically when present.

macOS Daemon Logs

When installed via launchd, logs are written to:

~/.brb/logs/daemon.out.log
~/.brb/logs/daemon.err.log

Requirements

• Node.js 20+
• A real local git repo
• A running BRB service endpoint

Troubleshooting

Repo is not registered

Run:

cd /path/to/repo
brb init

command not found: brb

Your global npm bin directory is probably not on PATH. Reinstall globally and ensure npm's global bin path is available in your shell.

Syncs are not happening

Check:

• the repo is registered in ~/.brb
• the service URL is reachable
• the repo is being watched
• you waited past the quiet window

macOS daemon is installed but not running

Check:

launchctl list | grep com.brb.daemon
tail -f ~/.brb/logs/daemon.err.log

Compatibility

• Package name: brbgit
• Primary command: brb
• Legacy command alias: git-agent