Skip to main content

Team Setup

The new Bitloops model separates team-shared repo policy from machine-specific daemon configuration.

Each developer has:

  • their own global daemon config
  • their own daemon data, cache, and state directories
  • their own provider credentials

The repository can carry:

  • .bitloops.toml for shared capture policy
  • optional imported knowledge TOML files

Each developer may also keep:

  • .bitloops.local.toml for personal overrides

Team Onboarding Flow​

1. Fastest onboarding path​

The fastest way to get started from inside the repository is:

bitloops init --install-default-daemon --sync=true

That single command bootstraps the default daemon service if needed, creates .bitloops.local.toml, installs hooks, and follows the initial current-state sync. Use the explicit bitloops start --create-default-config path below when someone needs to inspect or customise their daemon config before bootstrapping the repo.

bitloops start --create-default-config

On a fresh machine, use --create-default-config once. That writes the default global daemon config and creates the default local SQLite, DuckDB, and blob-store paths.

Interactive bitloops start can also prompt to create the default config when it is missing. During that first bootstrap, Bitloops asks for telemetry consent unless you pass --telemetry, --telemetry=false, or --no-telemetry.

2. Configure machine-specific stores and credentials​

config.toml
[stores.relational]
sqlite_path = "/Users/alex/.local/share/bitloops/stores/relational/relational.db"

[stores.events]
duckdb_path = "/Users/alex/.local/share/bitloops/stores/event/events.duckdb"

[knowledge.providers.github]
token = "${GITHUB_TOKEN}"

3. Bootstrap a project locally​

From the repository root or a subproject directory:

bitloops init --install-default-daemon --sync=true
bitloops init --sync=true

The fastest default path is bitloops init --install-default-daemon --sync=true. Use plain bitloops init when the daemon is already running, or when a developer has already bootstrapped their daemon separately.

This creates .bitloops.local.toml, adds it to .git/info/exclude, and installs or reconciles hooks.

When you use bitloops init --install-default-daemon and embeddings are not already configured, interactive init asks whether to use Bitloops cloud, the local runtime, or skip embeddings for now. Bitloops cloud is the recommended default, and the managed local runtime still downloads and warms asynchronously when that local option is selected.

In an interactive terminal, plain bitloops init also asks whether you want to install that same default local embeddings setup when embeddings are still unconfigured.

bitloops init can also queue an initial DevQL current-state sync after hooks are installed. Use --sync=true to run it immediately, or --sync=false to skip it. If you omit --sync in an interactive terminal, Bitloops asks after hook setup whether you want to sync the codebase.

In non-interactive mode, bitloops init requires --sync=true or --sync=false.

bitloops init still does not run DevQL ingest. Use bitloops devql tasks enqueue --kind ingest when you want to populate checkpoint, commit, and event history.

Use --agent <name> repeatedly when a team wants to pin the supported agent set during bootstrap. For example:

bitloops init --sync=false --agent claude-code --agent codex

If telemetry consent later becomes unresolved for an existing daemon config, interactive bitloops init can ask again. Non-interactive runs require an explicit telemetry flag.

4. Commit shared project policy when you need it​

.bitloops.toml
[capture]
enabled = true
strategy = "manual-commit"

[watch]
watch_debounce_ms = 750
watch_poll_fallback_ms = 2500

[imports]
knowledge = ["bitloops/knowledge.toml"]

One simple workflow is to start from the generated .bitloops.local.toml, rename or copy the relevant sections into .bitloops.toml, and commit the shared file.

5. Open the dashboard or keep using the daemon​

bitloops dashboard

Local Overrides​

Personal overrides go in .bitloops.local.toml, which bitloops init ensures is ignored through .git/info/exclude.

Example:

.bitloops.local.toml
[capture]
enabled = false

Use bitloops enable and bitloops disable to toggle [capture].enabled in the nearest discovered project policy without reinstalling hooks.

Use bitloops enable --install-embeddings or bitloops daemon enable --install-embeddings when a developer also needs the default local embeddings profile added to the effective daemon config. Interactive bitloops enable offers that setup automatically with a default-yes [Y/n] prompt when embeddings are not already configured.

If telemetry consent is unresolved for an existing daemon config, interactive bitloops enable can ask before it edits project policy.

What Not To Commit​

Do not commit:

  • provider secrets
  • machine-specific store paths unless your team explicitly standardises them
  • daemon runtime state

Those belong to each developer’s daemon config or local environment.