Sync model
How local changes become durable remote commits
BRB keeps the local repo primary, batches file-system changes after a pause, syncs deltas to a repo agent, and commits remotely with conversation-aware messages.
Core concepts
•https://docs.brbgit.com/sync-and-commitsSource of truth
- The local repo is primary.
- The repo agent is the working replica and continuity layer.
- Cloudflare Artifacts is the canonical Git history and file-tree remote when enabled.
- BRB does not auto-commit the user’s local repo.
Private by default
- Every repo belongs to one authenticated owner.
- The dashboard only lists repos for the signed-in account.
- The CLI syncs as the currently logged-in user.
Adaptive batching
| Parameter | Description | Default |
|---|---|---|
| quiet-window-ms | Wait for a natural editing pause before syncing. | 5000 |
| max-batch-window-ms | Force a sync if continuous editing goes on for too long. | 30000 |
| min-resync-gap-ms | Prevent noisy back-to-back syncs. | 2000 |
Commit message generation
Remote commit messages use changed files, checkpoints, recent commit history, and synced conversation context when available. Low-signal incidental changes are down-ranked so the title tracks the real user-facing work.
Commit authorship
BRB prefers your local git user.name if it exists, and falls back to BRB Sync for remote sync-created commits.
Cloudflare Artifacts
- Artifacts is optional and backend-managed by BRB.
- BRB remains the continuity and auth layer.
- Artifacts stores the canonical Git history and file trees.
- BRB attaches commit-level continuity metadata to BRB-created commits so history can render cleaner summaries and session context.
- The current rollout uses the Artifacts REST control plane and repo-scoped Git tokens.
Cloudflare Artifacts source of truth
- Artifacts is optional and configured at the app level plus per-repo provisioning.
- BRB uses Artifacts as the canonical Git remote and keeps continuity metadata in BRB.
- BRB can fork isolated session repos from the canonical Artifacts repo.
- 1Set the Artifacts token on the app Worker.
- 2Create or import a BRB repo.
- 3Create a BRB commit by running watch mode or a manual sync.
- 4Confirm the same commit appears in the Artifacts remote.
Sync states in the UI
- Not watching means no watcher or daemon heartbeat is active.
- Collecting means BRB is still batching changes.
- Syncing means a delta is being pushed right now.
- Paused means sync is blocked, for example by secret scanning.
- Watching means the repo is healthy and currently up to date.