Why beads worktree inside .git dir?

Why does Beads (bd) create worktrees inside .git dir instead of as sibling dirs, which is the normal way?

Beads creates worktrees inside .git/beads-worktrees/ rather than as sibling directories because these worktrees are internal plumbing, not user-facing parallel development directories.

The core reason: Beads' "sync branch" feature needs to commit issue updates to a separate branch (like beads-metadata) without switching your working directory away from your current branch. To do this, it creates a lightweight worktree with sparse checkout containing only .beads/. The daemon uses this hidden worktree to auto-commit and push issue changes while leaving your main checkout untouched.

Why inside .git/ specifically:

The placement under .git/beads-worktrees/<branch>/ is intentional for containment and invisibility. It keeps the worktree hidden from IDEs, linters, file watchers, and build tools that would otherwise traverse sibling directories. It avoids cluttering your project structure with extra folders. Beads already has write access to .git/ (it must, to operate), so there's no need to handle external directory permissions or guess a safe sibling location. Cleanup is simple: rm -rf .git/beads-worktrees && git worktree prune.

Is this unusual? Git doesn't require worktrees to be siblings - that's just a common convention for human-facing parallel development. Placing worktrees under .git/ is legitimate for tool-created internal workspaces. Other tools like newt use a similar pattern (.newt/ directory).

The main gotcha: Git considers the sync branch "checked out" in that worktree, so you'll get "branch already checked out at .git/beads-worktrees/..." if you try to check out the same branch elsewhere. That's why Beads pushes you toward a dedicated sync branch rather than using main.

Source: WORKTREES.md and internal/syncbranch/worktree.go

Above answer courtest of Devin, https://app.devin.ai/. Extrodinary. I gave it only that opening sentence, with poorer grammer, and did not link to the beads repo.