From 92f2e1db8b143b3f149f6648cef2fe4acc685eec Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Sat, 27 Dec 2025 22:04:20 -0800
Subject: [PATCH] docs: add Database Redirects section to ADVANCED.md (bd-8x43)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the .beads/redirect feature for sharing databases across
multiple clones, and the new `bd where` command for debugging.

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

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

diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md
index 6edb58a6..787e66d4 100644
--- a/docs/ADVANCED.md
+++ b/docs/ADVANCED.md
@@ -7,6 +7,7 @@ This guide covers advanced features for power users and specific use cases.
 - [Renaming Prefix](#renaming-prefix)
 - [Merging Duplicate Issues](#merging-duplicate-issues)
 - [Git Worktrees](#git-worktrees)
+- [Database Redirects](#database-redirects)
 - [Handling Import Collisions](#handling-import-collisions)
 - [Custom Git Hooks](#custom-git-hooks)
 - [Extensible Database](#extensible-database)
@@ -197,6 +198,75 @@ bd automatically detects when you're in a worktree and shows a prominent warning
 **Why It Matters:**
 The daemon maintains its own view of the current working directory and git state. When multiple worktrees share the same `.beads` database, the daemon may commit changes intended for one branch to a different branch, leading to confusion and incorrect git history.
 
+## Database Redirects
+
+Multiple git clones can share a single beads database using redirect files. This is useful for:
+- Multi-agent setups where several clones work on the same issues
+- Development environments with multiple checkout directories
+- Avoiding duplicate databases across clones
+
+### Setting Up a Redirect
+
+Create a `.beads/redirect` file pointing to the shared database location:
+
+```bash
+# In your secondary clone
+mkdir -p .beads
+echo "../main-clone/.beads" > .beads/redirect
+
+# Or use an absolute path
+echo "/path/to/shared/.beads" > .beads/redirect
+```
+
+The redirect file should contain a single path (relative or absolute) to the target `.beads` directory.
+
+**Example setup:**
+```
+repo/
+├── main-clone/
+│   └── .beads/
+│       └── beads.db      ← Actual database
+├── agent-1/
+│   └── .beads/
+│       └── redirect      ← Points to ../main-clone/.beads
+└── agent-2/
+    └── .beads/
+        └── redirect      ← Points to ../main-clone/.beads
+```
+
+### Checking Active Location
+
+Use `bd where` to see which database is actually being used:
+
+```bash
+bd where
+# /path/to/main-clone/.beads
+#   (via redirect from /path/to/agent-1/.beads)
+#   prefix: bd
+#   database: /path/to/main-clone/.beads/beads.db
+
+bd where --json
+# {"path": "...", "redirected_from": "...", "prefix": "bd", "database_path": "..."}
+```
+
+### Limitations
+
+- **Single-level redirects only**: Redirect chains are not followed (A → B → C won't work)
+- **Target must exist**: The redirect target directory must exist and contain a valid database
+- **Daemon coordination**: All clones share the same daemon when using redirects
+
+### When to Use Redirects
+
+**Good use cases:**
+- Multiple AI agents working on the same project
+- Parallel development clones (feature work, bug fixes)
+- Testing clones that should see production issues
+
+**Not recommended for:**
+- Separate projects (use separate databases)
+- Long-lived forks (they should have their own issues)
+- Git worktrees (use `--no-daemon` instead, see above)
+
 ## Handling Git Merge Conflicts
 
 **With hash-based IDs (v0.20.1+), ID collisions are eliminated.** Different issues get different hash IDs, so concurrent creation doesn't cause conflicts.