Core Concepts

Syncing & tracking

Once a folder is linked, sync reconciles it with the cloud — pulling down skills and instructions a teammate updated, while preserving your local edits. Tracking is the optional flip side: routing your harness's LLM traffic through Brainbase so every session shows up under the agent.

Syncing

sync computes drift between your checkout and the cloud using the per-component hashes recorded in .brainbase/sync-state.json (gitignored), then applies changes. Force a harness or scope when the folder supports more than one.

bash

brainbase sync                          # reconcile with the cloud
brainbase sync --harness claude-code    # force a harness
brainbase sync --scope project          # force install scope

agent versions restore rolls the agent back in the cloud and leaves your folder alone, so the folder is behind the cloud afterwards. Run brainbase agent pull before you edit or push again.

Tracking conversations

Tracking is opt-in. When enabled, the CLI routes a harness's traffic through Brainbase so sessions are searchable and attributed to the agent. Only claude-code and codex can be tracked; for every other harness no traffic is rerouted, even with tracking on. You can opt in at either agent create time (with --track) or link time (where it's on by default; skip it with --no-tracking).

bash

brainbase agent create --track   # opt in when creating the agent
brainbase link --no-tracking     # link without routing LLM traffic

Drift is computed, not guessed

Sync state is per-checkout and never committed, so two clones of the same repo each track their own drift independently. See Files & state for what's written where.