From 4ffbab531195d8882bc5f136abf4db2d94cf6ae1 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Thu, 25 Dec 2025 20:48:59 -0800
Subject: [PATCH] docs(worktrees): Add 'Fully Separate Beads Repository'
 section (GH#195)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the BEADS_DIR workflow for storing beads in a completely
separate git repository from your code. This feature was added in
PR #533 by @dand-oss but wasn't documented.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/WORKTREES.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/docs/WORKTREES.md b/docs/WORKTREES.md
index a3c388de..dc9392bd 100644
--- a/docs/WORKTREES.md
+++ b/docs/WORKTREES.md
@@ -434,6 +434,91 @@ bd create "Add profile UI components" -t task -p 2
 # Clean merge back to main when ready
 ```
 
+## Fully Separate Beads Repository
+
+For users who want complete separation between code history and issue tracking, beads supports storing issues in a completely separate git repository.
+
+### Why Use a Separate Repo?
+
+- **Clean code history** - No beads commits polluting your project's git log
+- **Shared across worktrees** - All worktrees can use the same BEADS_DIR
+- **Platform agnostic** - Works even if your main project isn't git-based
+- **Monorepo friendly** - Single beads repo for multiple projects
+
+### Setup
+
+```bash
+# 1. Create a dedicated beads repository (one-time)
+mkdir ~/my-project-beads
+cd ~/my-project-beads
+git init
+bd init --prefix myproj
+
+# 2. Add a remote for cross-machine sync (optional)
+git remote add origin git@github.com:you/my-project-beads.git
+git push -u origin main
+```
+
+### Usage
+
+Set `BEADS_DIR` to point at your separate beads repository:
+
+```bash
+cd ~/my-project
+export BEADS_DIR=~/my-project-beads/.beads
+
+# All bd commands now use the separate repo
+bd create "My task" -t task
+bd list
+bd sync  # commits to ~/my-project-beads, pushes there
+```
+
+### Making It Permanent
+
+**Option 1: Shell profile**
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export BEADS_DIR=~/my-project-beads/.beads
+```
+
+**Option 2: direnv (per-project)**
+```bash
+# In ~/my-project/.envrc
+export BEADS_DIR=~/my-project-beads/.beads
+```
+
+**Option 3: Wrapper script**
+```bash
+# ~/bin/bd-myproj
+#!/bin/bash
+BEADS_DIR=~/my-project-beads/.beads exec bd "$@"
+```
+
+### How It Works
+
+When `BEADS_DIR` points to a different git repository than your current directory:
+
+1. `bd sync` detects "External BEADS_DIR"
+2. Git operations (add, commit, push, pull) target the beads repo
+3. Your code repository is never touched
+
+This was contributed by @dand-oss in [PR #533](https://github.com/steveyegge/beads/pull/533).
+
+### Combining with Worktrees
+
+This approach elegantly solves the worktree isolation problem:
+
+```bash
+# All worktrees share the same external beads repo
+export BEADS_DIR=~/project-beads/.beads
+
+cd ~/project/main       && bd list  # Same issues
+cd ~/project/feature-1  && bd list  # Same issues
+cd ~/project/feature-2  && bd list  # Same issues
+```
+
+No daemon conflicts, no branch confusion - all worktrees see the same issues because they all use the same external repository.
+
 ## See Also
 
 - [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - General git integration guide