- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
website docs, plugin/npm docs, examples, and doctor hints.
- Standardized on:
- CGO_ENABLED=0 go install ... for server-mode only
- CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
capable
- Added scripts/check-go-install-guidance.sh and wired it into CI.
- Updated default.nix to use gms_pure_go instead of ICU flags.
Validation passed locally:
- make test
- golangci-lint run --build-tags=gms_pure_go ./...
- ./scripts/check-go-install-guidance.sh
- ./scripts/check-build-tags.sh
- go test -tags gms_pure_go ./cmd/bd/doctor
- doc flag check
Add ServerSocket config field and BEADS_DOLT_SERVER_SOCKET env var to
connect to Dolt via unix sockets instead of TCP. This eliminates port
conflicts between concurrent projects and simplifies sandbox integration.
- Wire --server-socket CLI flag through bd init and bd dolt set (dolt.socket)
- Add GetDoltServerSocket() to configfile with env var precedence
- Socket mode disables auto-start with socket-specific error hints
- TLS settings honored regardless of transport
- Integration test: starts dolt sql-server --socket, verifies end-to-end SQL
- Document in README.md server mode table
Closes#2939
* feat(docs): version Docusaurus site and align llms-full with snapshots
Add docs version 1.0.0, version dropdown, lastVersion defaulting to stable,
merged markdown config, and RELEASING steps for future doc snapshots.
generate-llms-full.sh reads the latest entry in versions.json.
README links the published documentation site.
Closes#2644
Made-with: Cursor
* fix(docs): update org URLs to gastownhall and refresh 1.0.0 snapshot
- Update default orgName in docusaurus.config.ts from steveyegge to
gastownhall to match the repo's new home
- Update hardcoded steveyegge URLs in generate-llms-full.sh
- Refresh versioned_docs 1.0.0 snapshot to include quickstart changes
from #3032 which merged after the original snapshot was taken
- Regenerate llms-full.txt with corrected URLs and updated content
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: narrow cross-version smoke CI triggers and warn on high skip rate
Remove push-to-main and PR triggers from cross-version smoke test
workflow — 30-45 min runtime is too costly for every push. Keep tag
pushes (releases/RCs) and manual dispatch.
Add a visible warning when >80% of tested versions are skipped, printed
to stderr and GitHub step summary. Prevents silent "all passed" when
nearly nothing actually ran.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: add .buildflags for consistent ICU build configuration
Amp-Thread-ID: https://ampcode.com/threads/T-019d5c3f-42eb-7794-8d59-524bbf77bdf8
Co-authored-by: Amp <amp@ampcode.com>
* Add analysis of getting-started docs: necessity vs. fixable errors
Analyzes ~3,200 lines of getting-started documentation across 9 files.
Finds ~50% of the content compensates for tool-level UX gaps that should
be fixed rather than documented. Categorizes every section as genuinely
necessary, useful reference, workaround for fixable issue, or redundant.
Includes specific recommendations for both tool fixes and doc consolidation.
Requested by @csells.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* Streamline getting-started docs: reduce noise, fix user-facing paths
QUICKSTART.md:
- Change all ./bd to bd (reflects installed binary, not local build)
- Replace go-build install section with brew/npm + link to INSTALLING.md
- Remove Notion sync, database maintenance, and migration sections
(these are advanced topics, not quickstart material)
- Add "Database maintenance" link to Next Steps
README.md:
- Consolidate installation from ~30 lines to ~8 lines
- Remove CGO/build-from-source details (belong in INSTALLING.md)
- Add links to INSTALLING.md sections for all install methods
INSTALLING.md:
- Demote go install/source to "Contributors / Go developers" in matrix
- Move Build Dependencies section after platform installs, retitle to
"Build Dependencies (Contributors Only)" with skip-if-prebuilt note
- Add cross-reference to TROUBLESHOOTING.md in troubleshooting section
Net effect: -91 lines, clearer separation between user and contributor
paths, less noise in the first-time experience.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: detect permission errors in bd init with platform-specific guidance
On Windows, Controlled Folder Access can block bd init from creating
.beads/ with no useful error. Now detects os.IsPermission and prints
specific guidance for Windows (CFA whitelist instructions) and Unix
(ls -la / chmod suggestions) instead of a generic failure message.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: add circuit breaker cleanup to bd doctor --fix
Stale circuit breaker files in /tmp/beads-circuit/ can block all bd
operations. Previously users had to manually rm these files. Now
bd doctor detects stale breaker files as a fixable check, and
bd doctor --fix clears them automatically via CleanStaleCircuitBreakerFiles.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* feat: warn about multiple bd binaries in PATH
bd version now scans PATH for duplicate bd executables and warns when
more than one is found. This catches the common case where go install
and Homebrew binaries coexist, causing version confusion. Symlinks
are resolved to avoid false positives.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: show holding process PID in database lock errors
When the Dolt database is locked, the error message now tries to
identify the holding process by scanning /proc for bd/dolt processes.
On Linux, users see e.g. "Process 12345 (bd/dolt) may be holding
the lock." Gracefully degrades to the previous message on platforms
without /proc (macOS, Windows, FreeBSD).
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: only flag circuit breaker files as stale after TTL expires
CheckCircuitBreaker() was counting any open/half-open breaker as stale
regardless of age. This could reset a legitimately active breaker
during a real outage. Now uses the same 5-minute staleness threshold
as CleanStaleCircuitBreakerFiles() — only breakers older than 5 minutes
(from TrippedAt or LastFailure) are flagged for cleanup.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: correct broken doc anchors in README installation links
The "go install" and "from source" links pointed to nonexistent anchors
in INSTALLING.md. Found during review checklist testing.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: suppress gosec G304 false positive in circuit breaker check
Path comes from filepath.Glob with a controlled pattern, matching
the same nolint pattern used in internal/storage/dolt/circuit.go.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Amp <amp@ampcode.com>
Beads' storage backend is Dolt, not git. Git integration (hooks, repo
discovery, identity) is optional — `BEADS_DIR` + `--stealth` provides
fully functional git-free operation with zero git calls.
Changes across 15 files:
- Replace all "git-backed" references with "Dolt-powered" or "Dolt-backed"
- Add "Git-Free Usage" section to README.md documenting BEADS_DIR + --stealth
- Fix stale "JSONL" storage reference in llms-full.txt
- Update SKILL.md to mark git as optional prerequisite
Complements GH#2522 (stale command cleanup) — that PR fixed removed
commands, this one fixes misleading storage backend framing.
Remove references to SQLite as primary backend, JSONL auto-sync daemon,
daemon configuration settings, and daemon-based architecture descriptions.
Replace with Dolt-native equivalents: Dolt as primary storage, git hooks
for JSONL portability, direct database access, and Dolt server mode for
multi-writer scenarios. (woho.6)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document the --claim flag for bd update in both README.md and
CLI_REFERENCE.md. This atomic operation prevents race conditions
when multiple agents try to claim the same task from bd ready.
The --claim flag:
- Sets assignee to current user
- Sets status to in_progress
- Uses compare-and-swap semantics (fails if already claimed)
Also noted that bd stale can find abandoned claims.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(export): populate export_hashes after successful export (GH#1278)
Child issues created with --parent were missing from export_hashes table,
which affects integrity tracking and future incremental export features.
This fix ensures SetExportHash() is called for all exported issues:
- Updated ExportResult to include IssueContentHashes map
- Updated finalizeExport() to call SetExportHash() for each exported issue
- Updated exportToJSONLDeferred() to collect content hashes during export
- Updated performIncrementalExport() to collect content hashes for dirty issues
- Updated exportToJSONLWithStore() to call SetExportHash() after export
- Updated daemon's handleExport() to call SetExportHash() after export
Added test TestExportPopulatesExportHashes to verify the fix works for
both regular and hierarchical (child) issue IDs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: add GitHub Copilot integration guide
Add comprehensive documentation for using beads with GitHub Copilot in VS Code via the MCP server.
New files:
- docs/COPILOT_INTEGRATION.md - Complete setup guide with prerequisites, MCP tools reference, example workflows, troubleshooting, and FAQ
- website/docs/integrations/github-copilot.md - Shorter website version
Updated files:
- docs/INSTALLING.md - Added GitHub Copilot row to setup matrix and new "GitHub Copilot (VS Code)" section with quick setup steps
- website/docs/getting-started/ide-setup.md - Added GitHub Copilot section
- website/docs/integrations/mcp-server.md - Added VS Code / GitHub Copilot configuration examples for both .vscode/mcp.json and settings.json
Key clarifications:
- Beads is a system-wide CLI tool installed once, not cloned into projects
- The .beads/ directory only contains the issue database
- Added FAQ addressing "Do I need to clone beads?" explicitly
Fixes#148
* docs: add cross-platform paths for user-level VS Code MCP config
Add Linux and Windows paths alongside macOS for the VS Code
user-level MCP configuration. Users can now find the correct
path for their platform in a simple table format.
Paths by platform:
- macOS: ~/Library/Application Support/Code/User/mcp.json
- Linux: ~/.config/Code/User/mcp.json
- Windows: %APPDATA%\Code\User\mcp.json
Fixes#148
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* feat: update to use core tap for beads installation
Signed-off-by: Rui Chen <rui@chenrui.dev>
* remove custom tap related code and refs
Signed-off-by: Rui Chen <rui@chenrui.dev>
---------
Signed-off-by: Rui Chen <rui@chenrui.dev>
* fix(routing): auto-enable hydration and flush JSONL after routed create
Fixes split-brain bug where issues routed to different repos (via routing.mode=auto)
weren't visible in bd list because JSONL wasn't updated and hydration wasn't configured.
**Problem**: When routing.mode=auto routes issues to a separate repo (e.g., ~/.beads-planning),
those issues don't appear in 'bd list' because:
1. Target repo's JSONL isn't flushed after create
2. Multi-repo hydration (repos.additional) not configured automatically
3. No doctor warnings about the misconfiguration
**Changes**:
1. **Auto-flush JSONL after routed create** (cmd/bd/create.go)
- After routing issue to target repo, immediately flush to JSONL
- Tries target daemon's export RPC first (if daemon running)
- Falls back to direct JSONL export if no daemon
- Ensures hydration can read the new issue immediately
2. **Enable hydration in bd init --contributor** (cmd/bd/init_contributor.go)
- Wizard now automatically adds planning repo to repos.additional
- Users no longer need to manually run 'bd repo add'
- Routed issues appear in bd list immediately after setup
3. **Add doctor check for hydrated repo daemons** (cmd/bd/doctor/daemon.go)
- New CheckHydratedRepoDaemons() warns if daemons not running
- Without daemons, JSONL becomes stale and hydration breaks
- Suggests: cd <repo> && bd daemon start --local
4. **Add doctor check for routing+hydration mismatch** (cmd/bd/doctor/config_values.go)
- Validates routing targets are in repos.additional
- Catches split-brain configuration before users encounter it
- Suggests: bd repo add <routing-target>
**Testing**: Builds successfully. Unit/integration tests pending.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* test(routing): add comprehensive tests for routing fixes
Add unit tests for all 4 routing/hydration fixes:
1. **create_routing_flush_test.go** - Test JSONL flush after routing
- TestFlushRoutedRepo_DirectExport: Verify direct JSONL export
- TestPerformAtomicExport: Test atomic file operations
- TestFlushRoutedRepo_PathExpansion: Test path handling
- TestRoutingWithHydrationIntegration: E2E routing+hydration test
2. **daemon_test.go** - Test hydrated repo daemon check
- TestCheckHydratedRepoDaemons: Test with/without daemons running
- Covers no repos, daemons running, daemons missing scenarios
3. **config_values_test.go** - Test routing+hydration validation
- Test routing without hydration (should warn)
- Test routing with correct hydration (should pass)
- Test routing target not in hydration list (should warn)
- Test maintainer="." edge case (should pass)
All tests follow existing patterns and use t.TempDir() for isolation.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(tests): fix test failures and refine routing validation logic
Fixes test failures and improves validation accuracy:
1. **Fix routing+hydration validation** (config_values.go)
- Exclude "." from hasRoutingTargets check (current repo doesn't need hydration)
- Prevents false warnings when maintainer="." or contributor="."
2. **Fix test ID generation** (create_routing_flush_test.go)
- Use auto-generated IDs instead of hard-coded "beads-test1"
- Respects test store prefix configuration (test-)
- Fixed json.NewDecoder usage (file handle, not os.Open result)
3. **Fix config validation tests** (config_values_test.go)
- Create actual directories for routing paths to pass path validation
- Tests now verify both routing+hydration AND path existence checks
4. **Fix daemon test expectations** (daemon_test.go)
- When database unavailable, check returns "No additional repos" not error
- This is correct behavior (graceful degradation)
All tests now pass:
- TestFlushRoutedRepo* (3 tests)
- TestPerformAtomicExport
- TestCheckHydratedRepoDaemons (3 subtests)
- TestCheckConfigValues routing tests (5 subtests)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: clarify when git config beads.role maintainer is needed
Clarify that maintainer role config is only needed in edge case:
- Using GitHub HTTPS URL without credentials
- But you have write access (are a maintainer)
In most cases, beads auto-detects correctly via:
- SSH URLs (git@github.com:owner/repo.git)
- HTTPS with credentials
This prevents confusion - users with SSH or credential-based HTTPS
don't need to manually configure their role.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix(lint): address linter warnings in routing flush code
- Add missing sqlite import in daemon.go
- Fix unchecked client.Close() error return
- Fix unchecked tempFile.Close() error returns
- Mark unused parameters with _ prefix
- Add nolint:gosec for safe tempPath construction
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Roland Tritsch <roland@ailtir.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* feat: comprehensive NixOS support improvements
This commit adds full NixOS support and automates Nix package maintenance:
## Static Linux Binaries for NixOS
Changes .goreleaser.yml to create static Linux binaries:
- Set CGO_ENABLED=0 for Linux amd64 and arm64 builds
- Remove cross-compiler dependencies (aarch64-linux-gnu-gcc)
- Simplifies build process while fixing NixOS compatibility
Static binaries work on all Linux distributions including NixOS, Alpine,
and musl-based distros without dynamic linker dependencies.
## Automated default.nix Version Management
Adds default.nix to the version bump workflow:
- Updates default.nix version field in bump-version.sh (new step 9)
- Adds default.nix to version verification checks
- Prevents version drift (was 5 releases behind: 0.42.0 vs 0.47.0)
- Updates README.md to remove glibc 2.32+ requirement
## Automated vendorHash Management
Creates scripts/update-nix-vendorhash.sh to automate vendorHash updates:
- Automatically detects correct hash by triggering Nix build error
- Extracts hash from error message and updates default.nix
- Verifies update with clean build
- Eliminates error-prone manual copy-paste workflow
- Works with local Nix OR Docker (uses nixos/nix image automatically)
Integrates vendorHash check into bump-version.sh:
- Detects when go.mod or go.sum have changed
- Prompts to run vendorHash update script interactively
- Catches synchronization issues at release time
## Documentation
Updates AGENTS.md with Nix package maintenance guide:
- Documents when and how to update vendorHash
- Recommends automated script as primary method
- Provides manual and alternative methods as fallback
- Notes Docker fallback for maintainers without Nix
## Impact
- NixOS users can now install via standard methods
- Nix package version stays synchronized automatically
- vendorHash updates work without Nix installed (via Docker)
- vendorHash updates are caught during release workflow
- All Linux users benefit from more portable binaries
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* fix: address PR review feedback for NixOS support
Fixes three issues identified in PR review:
1. Replace undefined log_* functions in bump-version.sh with existing
echo pattern (log_warning, log_info, log_success, log_error were
called but not defined)
2. Update default.nix version from 0.42.0 to 0.47.0 to fix version
drift with cmd/bd/version.go
3. Remove Nix Package Maintenance section from AGENTS.md per beads
architecture (use bd prime for dynamic context, keep AGENTS.md
minimal)
* fix: update versions to 0.47.1 after merge with main
- Update claude-plugin plugin.json to 0.47.1
- Update default.nix to 0.47.1
- Fixes version check failures after merging latest main branch
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
- Create docs/COMMUNITY_TOOLS.md with curated list of community-built tools ranked by activity
- Include tools from README.md and GitHub discussion #276
- Organize into categories: Terminal UIs, Web UIs, Editor Extensions, Native Apps, Historical
- Update README.md to reference the new dedicated page
Update docs to reflect CLI command restructuring:
- migrate-tombstones → migrate tombstones
- bd quickstart is now hidden, point to docs/QUICKSTART.md
- Add CLI consolidation section to CHANGELOG.md
- Remove quickstart from command tables
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Makes antivirus false positive documentation more discoverable.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
DeepWiki provides up-to-date documentation people can talk to, for every public repo in the world (after being added to it's index). Adding this badge to a repository Readme tells DeepWiki to refresh it's docs automatically.
The DeepWiki link for Beads is
https://deepwiki.com/steveyegge/beads
Adds back third-party tools removed in succinct README PR.
Includes beads.el Emacs package (closes#610).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The succinct README PR had Google search URLs instead of relative paths.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Three changes to fix deleted issues resurrecting during bd sync:
1. daemon handleDelete now uses CreateTombstone instead of DeleteIssue
- internal/rpc/server_issues_epics.go
2. sync.go exportToJSONL now includes IncludeTombstones:true
- cmd/bd/sync.go
3. server_export_import_auto.go handleExport and auto-export now include
tombstones in SearchIssues filter
- internal/rpc/server_export_import_auto.go
Also adds README.md documentation for sync.branch mode (bd-dsdh):
- Explains "always dirty" working tree behavior
- Shell alias tip: gs='git status -- ":!.beads/"'
- When to use bd sync --merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changed all user-facing documentation and help text to use `in_progress`
(underscore) instead of `in-progress` (hyphen) to match the canonical
status value.
Files updated:
- cmd/bd/ready.go - Short description
- cmd/bd/status.go - Long description
- commands/stats.md - Action suggestion
- README.md - Workflow description
Note: CSS class names, HTML IDs, and GitHub label mappings intentionally
kept with hyphens as they follow different conventions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add JSONL-only mode detection in ensureStoreActive() with context-aware
error messages that suggest correct actions based on project state
- Improve error messages in main.go to detect JSONL presence and suggest
appropriate solutions (bd init, --no-db flag, or config.yaml setting)
- Update documentation to use issues.jsonl as canonical filename:
- AGENT_INSTRUCTIONS.md, README.md, resolve-beads-conflict.md
- docs/GIT_INTEGRATION.md
- Update hook template comments to clarify issues.jsonl is canonical
while maintaining backward compatibility for beads.jsonl
Fixes#534🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds comprehensive Git worktree support for beads issue tracking:
Core changes:
- New internal/git/gitdir.go package for worktree detection
- GetGitDir() returns proper .git location (main repo, not worktree)
- Updated all hooks to use git.GetGitDir() instead of local helper
- BeadsDir() now prioritizes main repository's .beads directory
Features:
- Hooks auto-install in main repo when run from worktree
- Shared .beads directory across all worktrees
- Config option no-install-hooks to disable auto-install
- New bd worktree subcommand for diagnostics
Documentation:
- New docs/WORKTREES.md with setup instructions
- Updated CHANGELOG.md and AGENT_INSTRUCTIONS.md
Testing:
- Updated tests to use exported git.GetGitDir()
- Added worktree detection tests
Co-authored-by: Claude <noreply@anthropic.com>
Closes: #478
- Clarify that `bd ready` shows issues ready to work on (#512)
- Update git hooks install command from deprecated script to `bd hooks install` (#513)
- Fix Claude Code plugin local install: use `./beads` not `.`, clarify shell vs CC commands (#514)
Fixes#512, #513, #514🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add mise (polyglot runtime manager) as an installation option using the
ubi backend to install from GitHub releases.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add documentation for users experiencing npm postinstall failures in Claude Code web environments due to network restrictions.
Closes: bd-8q0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed incorrect reference to "1% collision point at ~1,217" when 1,217
is actually the 50% collision point for 5-char hashes. The 1% point
is ~153.
Fixes#407🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Removes global gitattributes setup from stealth mode, keeping only the global gitignore configuration. CI failures are pre-existing (TestZFCSkipsExportAfterImport timeout).