Auto-update behavior

bassclef auto-update is OFF by default. Here is what that means and how to change it.

Auto-update is OFF by default

bassclef will not fetch its own updates without you asking. If you clone a fresh copy today and never touch the config, bassclef will run the exact substrate version it shipped with. Your repo does not silently change because upstream shipped new rules.

This is the safest starting posture: you get predictable behavior, and you decide when to accept a new version.

The config file

Every repo that uses bassclef has a file at the root:

.bassclef-source.json

Inside it, the field auto_sync controls the behavior:

{
  "auto_sync": false
}

The default value is false. When false:

bassclef reads the substrate from your local clone at session start.
No network calls happen for substrate updates.
New skills, rules, or hooks upstream shipped do not appear in your repo until you pull them in manually.

Turning auto-update on

Two paths.

Manual — edit .bassclef-source.json and set auto_sync: true. Next session, bassclef fetches the newest release before running skills.

Conversational — type "enable auto-sync" in a Claude Code session. bassclef flips the flag for you and confirms the change. See the auto-sync conversational listener rule for the exact phrases.

Turning it back off

Say "disable auto-sync" in a session, or edit the file and set auto_sync: false. bassclef stops fetching on its own.

What happens when auto-update is on

At session start, bassclef checks the release feed. If a newer release exists, it pulls the tarball, verifies the checksum, and rewires the symlinks into your .claude/skills/, .claude/rules/, etc. Your repo files are not modified — the substrate is separate from your source.

If the fetch fails (network down, checksum mismatch, tarball missing), bassclef falls back to the last version it successfully fetched and tells you what went wrong. Your session still runs.

Why this matters

Two audiences read this page.

You, running bassclef in a solo repo — you want to know that bassclef will not surprise you at 2am with a new rule that breaks your existing workflow. It will not. That is the whole point of the default being OFF.

Your team, evaluating bassclef for shared use — you want to know that a team member cannot flip the auto-update switch and force a new version on the shared repo without a pull request. The .bassclef-source.json file is committed to your repo, so any change to auto_sync shows up in code review like any other config edit.

Failure-mode playbook — what to do when a bassclef update lands and something breaks
Install — how to install bassclef in the first place
Substrate config — full schema for .bassclef-source.json