BRB

How the system stays in sync without asking the user to think like Git

BRB turns a local coding repo into a continuously mirrored Cloudflare-hosted project. The user keeps working locally. BRB handles sync, commit creation, context capture, restore points, and visibility in the UI.

Local repo stays primary

The user edits files in a normal git repo on their machine.

Cloudflare agent mirrors it

Each repo maps to a Cloudflare durable agent that stores code and history.

UI shows live project state

The dashboard shows sync state, activity, conversation, commits, and restore points.

Open directly in a browser: /presentations/how-it-works.html Designed as a simple internal presentation deck
Core loop

The whole product in one flow

1. User edits locally

Files change in a normal repo like ~/github/sample.

→
2. Watcher notices changes

The CLI watch mode or daemon observes filesystem changes.

→
3. Quiet pause triggers sync

After a short pause, BRB batches the delta and syncs it.

4. Conversation context is attached

If Codex is working in that repo, the latest session transcript is also synced.

→
5. Cloudflare agent commits

The remote repo agent writes files, creates a git commit, and records a checkpoint.

→
6. UI updates

The project dashboard and detail page show the new state.

Architecture

What runs where

On the user’s machine
  • Local git repo
  • BRB CLI
  • watch or background daemon
  • Codex local session logs under ~/.codex/sessions/
  • Local registry under ~/.brb/registry.json
On Cloudflare
  • TanStack Start Worker for the app and API
  • One durable repo agent per project
  • Repo storage, commit history, sync status, checkpoints
  • Workers AI for high-signal commit messages
Key design choice

The user does not need to manually commit their local repo for BRB to stay useful. The remote repo agent becomes the continuous, agent-friendly project record.

Why the debounce exists

We wait for a pause so one burst of work becomes one meaningful commit

Quiet window

Sync after edits stop for a configured period, for example 5 seconds.

Max batch window

Force a sync during long editing bursts so the system does not wait forever.

Min resync gap

Prevents noisy back-to-back commits when tools save repeatedly.

Result

Instead of a commit for every file save, the user gets one commit per meaningful pause in the agent’s work.

Context-aware commits

Commit messages use more than filenames

Inputs used
  • Changed file paths and content previews
  • Recent synced conversation window
  • Latest user request
  • Latest assistant response
  • Recent commit titles to avoid repetition
What the system tries to do
  • Name the outcome, not the sync action
  • Lead with the primary change, not incidental churn
  • Write natural titles across frontend, auth, API, DB, tooling, and bug-fix work
  • Fallback cleanly if AI output is unavailable
Conversation continuity

Why syncing agent conversation matters

The problem

A project often starts in one coding agent, then moves to another when credits run out or the user changes tools.

The solution

BRB mirrors the coding conversation into the project so another agent can see what was asked, what was done, and what the recent commits mean.

Important rule

Conversation only attaches when the Codex session cwd matches the repo path being watched. That keeps project context scoped correctly.

Recovery

Restore points make agent work reversible

Every synced commit records a checkpoint

The system captures the visible repo snapshot and links it to the commit.

Restore creates a new commit

History stays auditable. Nothing silently rewinds in place.

UI makes it simple

The user sees restore points in the project detail page and can restore in one click.

What the UI shows

One dashboard for scanning, one detail page for understanding

Dashboard
  • All projects
  • Sync-state badges
  • Summary counts for watching, syncing, and errors
  • Filters for all, watching, syncing, errors, and idle
Project detail
  • Activity and sync state
  • Last commit and last message
  • Conversation transcript
  • Restore points
  • Recent sync activity timeline
What the user actually runs

Simple local workflow

Set up once

npm install -g brbgit

brb init --repo sample --source ~/github/sample

brb sync --source ~/github/sample

Then keep it live

brb watch --source ~/github/sample

or install the macOS daemon to watch every registered repo automatically.

Tested quality

How we know it holds up

Build verification

CLI and web app both build cleanly.

Replay corpus

Commit-message quality is tested across frontend, auth, API, DB, tooling, and bug-fix scenarios.

Integration flow

A real sample app is pushed, updated, deleted, and verified through the live API.