Beads Branching Strategies

[bryanhirsch]

Today, Beads works like Jira. Code and issue tracking have separate histories. The familiarity makes it intuitive. But once I start asking questions like, "Can I reset Beads when I reset my code?", it gets confusing, and the logic feels opaque.

I created a gist describing scenarios where tighter integration would be helpful and working draft proposal for refinements.

I'd value input if anyone has thoughts or use cases to add here. I'd be happy to develop a POC and get a PR submitted if this is a direction people want to go.

[bryanhirsch]

@peterkc, I really appreciated your response to @geerzo here #2164. Do you have thoughts or reactions re. branching strategies here?

[peterkc]

@bryanhirsch — the BD_BRANCH postmortem, the Fossil prior art analysis, the cherry-pick scaling table with concrete latency estimates — this proposal has depth. A few thoughts from running Dolt Server for beads across multiple repos with concurrent agents.

Strategy A as default is exactly right. My comment on #2164 covers this in detail, but the short version: beads tracks work completion, git tracks code availability. They're complementary state machines. The bd gate system with gh:pr type already bridges the gap between them. I've been running this pattern across multiple repos and it handles retry-after-failure without branching — close the beads, reset the branch, start fresh.

The bake-off scenario needs branch isolation. Running the same epic against multiple agents, keeping the winner's issue state, discarding the rest — that requires isolated write spaces. Your Strategy B handles it.

Where I'd push back is on the bundling. The proposal solves three distinct problems with one branching system:

Problem	Fundamental need	Simpler path
Retry after failure	Point-in-time restore	Dolt already has AS OF, dolt_history_*, DOLT_RESET. A bd snapshot wrapper around existing primitives covers this without branches
Agent bake-off	Speculative execution	bd branch --isolated using the existing Branch/Checkout/Merge API in store.go — that code already works
State consistency	Git-Dolt coupling	Either accept the decoupling (it works for us) or a lightweight anchor table recording {dolt_commit, git_commit} pairs — no pointer file in git

Solving each independently eliminates the pieces with the highest complexity-to-demand ratio: the cherry-pick messaging system, the strategy selection cascade, the BEADS_HEAD file writing to git on every Dolt commit, and the schema migration interaction with cherry-picks.

On user experience — #2332 has a user saying "I don't 'get' dolt and at this point I'm too afraid to ask." The Dolt transition is already a mental model shift. A single --isolated flag for bake-off users keeps the conceptual surface minimal. Three strategies with cross-branch messaging adds weight even for users who never leave Strategy A, because it appears in docs, error messages, and bd branch output.

The decomposition above isn't a rejection of the proposal's goals. It's how I'd ship each piece independently while keeping the option to compose them later if demand shows up.

[peterkc]

@bryanhirsch — built the branch and tested the full cycle against a Dolt server. bd reset --hard HEAD~1 works: git moves back, Dolt moves back, the 4th issue disappears, forward reset via reflog restores everything. The git: / dolt: output formatting is a good touch.

Left a detailed review on the PR covering one bug (isRebaseInProgress() breaks in worktrees — the codebase already has the fix via git.GetGitDir()), an onboarding gap (config.yaml not created by bd init), a test coverage matrix with gap analysis, and code quality items. All constructive — the core feature is solid.

[peterkc]

@bryanhirsch — saw the PR was closed. Hope the review feedback is still useful for the next iteration.

Separate from the PR: one tool worth trying for working in the beads codebase — colgrep. It's a semantic code search — a single Rust binary that finds code by meaning, not just text. Install instructions here.

colgrep init .                                    # one-time index (~30s)

Beads is 726 Go files. grep works when you know the exact function name. colgrep works when you know what you're looking for but not what it's called:

# Find how beads resolves git directories across worktrees
colgrep "worktree-aware git directory resolution" .
# -> internal/git/gitdir.go:90-102  (GetGitDir)

# Find where Dolt transactions are committed
colgrep "transaction commit boundary" .
# -> internal/storage/dolt/transaction.go:41-90

# Find how config survives DOLT_RESET
colgrep "config persistence across reset" .
# -> internal/config/yaml_config.go (YAML, not Dolt tables)

# Hybrid: semantic + regex filter
colgrep "error handling in merge" -e "conflict|resolve" .

Each of these replaces 5-10 minutes of grepping through unfamiliar code with a single query.

Using it with Claude Code: Add colgrep as an allowed tool in your project's .claude/settings.json, then Claude searches the codebase semantically before writing code, debugging, or reviewing:

// .claude/settings.json
{
  "permissions": {
    "allow": ["Bash(colgrep *)"]
  }
}

Then in CLAUDE.md or a rule:

## Semantic Search Before Code Changes

Run `colgrep "<what you need to understand>" .` before:
- Writing new functions (find existing utilities)
- Modifying unfamiliar code (understand patterns in use)
- Debugging errors (trace where the error originates)
- Filing issues or PR reviews (verify claims with evidence)

Read the top 3 results before proceeding.

For context — this is how I found the isRebaseInProgress() worktree bug during review. colgrep "rebase detection git directory worktree" . surfaced GetGitDir() as the #2 result, which led to the fix. But the same pattern applies to any task in the beads codebase.

[bryanhirsch]

@peterkc your feedback was very helpful! As I was addressing the rebase issue you identified, I realized a bunch of Phase 2 work leaked into this Phase 1 PR. I decided it would be cleaner to resubmit. Your message was also a good nudge for me to use this code in a local version for a few days and then submit. I suspect this'll shake out a few more issues.

Thanks so much for passing this tip along about colgrep! Very helpful!

[peterkc]

@bryanhirsch Sounds good. Let me know if you need any help or chat.

[bryanhirsch]

Thanks, @peterkc! Here's a refactored branch for a new PR:
bryanhirsch#1

I'm going to use this code for few days and see if I shake out any more kinks before I resubmit. If you want to try it or kick the tires here too, that'd be great! Happy to chat as well if you have any ideas to kick around here.