branch-config

Branch Configuration (_branch)

Branch detection and merge behavior, configured per-project in .claude/settings.local.json under the _branch key.

Script: ~/.claude/scripts/branch-detect.sh — single source of truth for branch resolution across all commands and hooks.

Schema

Field	Type	Default	Description
_branch.main	string|null	auto-detect	Override main branch name
_branch.session	string|null	auto-detect	Override session/working branch
_branch.merge_strategy	"ff-only" | "merge-commit" | "squash"	"ff-only"	Merge strategy for /finish-work and warp-drive

Auto-Detection (no config)

When _branch is not set, branch-detect.sh auto-detects:

1. Main branch: origin/HEAD → local main → local master → error
2. Session branch: current branch if not on main, otherwise null
3. Merge target: session branch if set, otherwise main
4. Merge strategy: ff-only

Examples

Default (no config needed)

Most repos need no configuration — detection just works.

{}

Output on a main-based repo while on feature/foo:

{"main":"main","session":"feature/foo","current":"feature/foo","on_main":false,"merge_target":"feature/foo","merge_strategy":"ff-only"}

Explicit session branch

Pin session branch so it persists even when on main (e.g., long-running dev branch):

{
  "_branch": {
    "session": "dev/sprint-3"
  }
}

Custom main branch (develop)

For repos using develop as the integration branch:

{
  "_branch": {
    "main": "develop"
  }
}

Squash merging

For projects that prefer squash merges:

{
  "_branch": {
    "merge_strategy": "squash"
  }
}

Merge Strategy → Git Flag Mapping

Strategy	Git flag	Behavior
ff-only	--ff-only	Fast-forward only, fails if diverged
merge-commit	--no-ff	Always create a merge commit
squash	--squash	Squash all commits into one

Consumer Commands

Command / Script	Uses
/start-work	Detects main for checkout; writes _branch.session after branch creation
/finish-work	Detects main for rebase/merge target
/warp-drive	Detects main, session, merge_target, merge_strategy for all merge operations
check-branch.sh hook	Detects main for branch enforcement
state-machine.js	Stores branch fields in warp-drive state