Created docs/PERFORMANCE_TESTING.md with comprehensive coverage of:
- Running benchmarks (make bench, make bench-quick)
- Running specific benchmarks
- Understanding benchmark output (ns/op, allocs/op)
- CPU profiling with pprof and flamegraphs
- Memory profiling
- User diagnostics (bd doctor --perf)
- Comparing performance with benchstat
- Optimization tips and common patterns
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Clarify bd merge help text: git merge driver, not for duplicate issues
- Add Do I Need the Daemon section to DAEMON.md
- Add daemon overview section to QUICKSTART.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Completes the deletion propagation epic (bd-imj) with all 9 subtasks:
- Cross-clone deletion propagation via deletions.jsonl
- bd deleted command for audit trail
- Auto-compact during sync (opt-in)
- Git history fallback with timeout and regex escaping
- JSON output for pruning results
- Integration tests for deletion scenarios
- Documentation in AGENTS.md, README.md, and docs/DELETIONS.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive documentation for the blocked_issues_cache optimization
that improved GetReadyWork performance from 752ms to 29ms (25x speedup).
Documentation locations:
- blocked_cache.go: Detailed package comment covering architecture,
invalidation strategy, transaction safety, edge cases, and future
optimizations
- ready.go: Enhanced comment at query site explaining the optimization
and maintenance triggers
- ARCHITECTURE.md: New section with diagrams, blocking semantics,
performance characteristics, and testing instructions
Closes bd-1w6i
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Document known Kaspersky false positive issue with Go binaries and
provide user workarounds.
Changes:
- Add comprehensive docs/ANTIVIRUS.md with:
- Explanation of why Go binaries trigger AV false positives
- Step-by-step exclusion instructions for Kaspersky, Windows Defender
- File integrity verification procedures
- False positive reporting guide
- FAQ section
- Update docs/TROUBLESHOOTING.md with quick reference section
- Close bd-t4u1: Kaspersky PDM:Trojan.Win32.Generic detection
Root cause: Kaspersky's heuristic detection flags Go binary patterns as
suspicious. This is an industry-wide issue affecting many Go projects.
Build already uses recommended optimizations (-s -w flags). Future
improvements (code signing, vendor whitelist) tracked separately.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Currently 'bd daemon' with no args immediately starts the daemon. This is
inconsistent with other daemon management commands like --stop, --status,
etc. and makes the command less discoverable for new users.
Changes:
- Add --start flag to explicitly start daemon
- Show help text when no operation flags provided
- Update auto-start logic to use --start flag
- Update startDaemon() to pass --start when forking
- Update all documentation to use 'bd daemon --start'
- Update MCP Python client error messages
The MCP docs already incorrectly showed 'bd daemon start' which doesn't
work, so this change fixes that documentation bug while improving UX.
Auto-start still works correctly - it now passes --start internally.
Fixes bd-gfu
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Max size: 10MB → 50MB per file
- Max backups: 3 → 7 files
- Max age: 7 → 30 days
- Updated tests and documentation
Resolves bd-t7ds
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements flexible error handling for export operations with four policies:
- strict: Fail-fast on any error (default for user exports)
- best-effort: Skip errors with warnings (default for auto-exports)
- partial: Retry then skip with manifest tracking
- required-core: Fail on core data, skip enrichments
Key features:
- Per-project configuration via `bd config set export.error_policy`
- Separate policy for auto-exports: `auto_export.error_policy`
- Retry with exponential backoff (configurable attempts/delay)
- Optional export manifests documenting completeness
- Per-issue encoding error handling
This allows users to choose the right trade-off between data integrity
and system availability for their specific project needs.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements GH#206 and bd-3djj: Add support for Aider AI pair programming
tool with beads issue tracking.
Changes:
- Added cmd/bd/setup/aider.go with InstallAider, CheckAider, RemoveAider
- Created .aider.conf.yml template with bd workflow instructions
- Added .aider/README.md template with quick reference
- Updated cmd/bd/setup.go to include aider subcommand
- Fixed cmd/bd/main.go to allow setup subcommands without database by
checking parent command name
- Added comprehensive docs/AIDER_INTEGRATION.md documentation
Key differences from Claude/Cursor integration:
- Aider requires explicit command execution via /run
- AI suggests bd commands rather than running autonomously
- Documentation emphasizes human-in-the-loop workflow
- Config instructs AI to always suggest, never execute
Usage:
bd setup aider # Install integration
bd setup aider --check # Verify installation
bd setup aider --remove # Remove integration
Resolves bd-3djj
Related to GH#206
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Overview: Added comprehensive test infrastructure to handle the large
test suite (41K LOC, 313 tests in cmd/bd alone) with automatic skipping
of known broken tests.
Changes:
- .test-skip: List of broken tests to skip (with GH issue references)
- scripts/test.sh: Smart test runner that auto-skips broken tests
- docs/TESTING.md: Comprehensive testing guide
- .claude/test-strategy.md: Quick reference for AI agents
- Updated Makefile to use new test script
Known Issues Filed:
- GH #355: TestFallbackToDirectModeEnablesFlush (database deadlock)
- GH #356: TestFindJSONLPathDefault (wrong JSONL filename)
Performance: 3min total (180s compilation, 3.8s execution)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Git merge drivers only support three placeholders:
- %O (ancestor/base)
- %A (current version)
- %B (other branch's version)
The code was incorrectly using %L and %R, which don't exist in git,
causing them to be passed through literally and breaking JSONL merges.
Changes:
- Fixed merge driver config in init.go, merge.go, README.md, docs
- Added detection in bd doctor with clear error messages
- Added auto-fix in bd doctor --fix
- Added proactive warning in bd sync before git pull
- Added reactive error detection after merge failures
- Updated all tests to use correct placeholders
Now users get helpful guidance at every step:
1. bd doctor detects the issue
2. bd doctor --fix auto-corrects it
3. bd sync warns before pulling if misconfigured
4. Error messages suggest bd doctor --fix when merge fails
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Relocate documentation files to centralize all .md files in docs/ directory
(except those with historical precedent in specific locations like commands/,
examples/, integrations/, etc.).
Files moved:
- cmd/bd/doctor/claude.md -> docs/CLAUDE_INTEGRATION.md
- cmd/bd/MAIN_TEST_REFACTOR_NOTES.md -> docs/MAIN_TEST_REFACTOR_NOTES.md
- cmd/bd/TEST_SUITE_AUDIT.md -> docs/TEST_SUITE_AUDIT.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Remove 5 obsolete documentation files (2,847 lines, 20% reduction):
Removed files:
- HASH_ID_DESIGN.md: Design doc for hash IDs (implemented in v0.20+, bd-166)
- contributor-workflow-analysis.md: Design analysis (superseded by MULTI_REPO_*.md)
- vc-feedback-on-multi-repo.md: Feedback on design (now implemented)
- import-bug-analysis-bd-3xq.md: Bug analysis for specific issue (likely fixed)
- TEST_OPTIMIZATION.md: One-time optimization doc (completed Nov 2025)
All removed files were historical design/analysis documents for features
that are now implemented and documented elsewhere.
Retained files:
- MULTI_REPO_HYDRATION.md: Referenced as internals documentation
- ROUTING.md: Active user-facing feature documentation
- EXCLUSIVE_LOCK.md: Integration documentation for external tools
- ADAPTIVE_IDS.md: Referenced by CONFIG.md
- COLLISION_MATH.md: Referenced by ADAPTIVE_IDS.md and CONFIG.md
Total documentation reduced from 14,043 to 11,196 lines.
Implements three quick fixes for users stuck in sandboxed environments
(e.g., Codex) where daemon cannot be stopped:
1. **--force flag for bd import**
- Forces metadata update even when DB is synced with JSONL
- Fixes stuck state caused by stale daemon cache
- Shows: "Metadata updated (database already in sync with JSONL)"
2. **--allow-stale global flag**
- Emergency escape hatch to bypass staleness check
- Shows warning: "⚠️ Staleness check skipped (--allow-stale)"
- Allows operations on potentially stale data
3. **Improved error message**
- Added sandbox-specific guidance to staleness error
- Suggests --sandbox, --force, and --allow-stale flags
- Provides clear fix steps for different scenarios
Also fixed:
- Removed unused import in cmd/bd/duplicates_test.go
Follow-up work filed:
- bd-u3t: Phase 2 - Sandbox auto-detection
- bd-e0o: Phase 3 - Daemon robustness enhancements
- bd-9nw: Documentation updates
Fixes#353 (Phase 1)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#312
Users were confused about which files should be committed after running
'bd init --branch beads-metadata'. The PROTECTED_BRANCHES.md doc now
clearly explains:
1. Files to commit to protected branch (main):
- .beads/.gitignore - Tells git what to ignore
- .gitattributes - Merge driver configuration
2. Files automatically gitignored (do NOT commit):
- .beads/beads.db - SQLite database (local only)
- .beads/daemon.* - Runtime files
- .beads/*.left/right.jsonl - Temporary merge artifacts
3. Files in sync branch (beads-metadata):
- .beads/beads.jsonl - Issue data (committed by daemon)
- .beads/metadata.json - Repository metadata
- .beads/config.yaml - Configuration template
Added step-by-step instructions in Quick Start section and a "What lives
in each branch" section to How It Works.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#299
Added comprehensive documentation to help new users understand what files
should be committed vs ignored after running bd init:
1. README.md:
- New "Files Created by bd init" section
- Clear lists of files to commit vs ignore
- Explains purpose of .gitattributes for team collaboration
2. docs/GIT_INTEGRATION.md:
- Enhanced .gitattributes section with IMPORTANT notice
- Explains why it must be committed (merge driver config)
- Lists benefits of intelligent JSONL merging
Key clarification: .gitattributes should be COMMITTED (not ignored) as it
configures git merge behavior for the entire team.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Critical fixes to code review findings:
1. Remove global state access from flushToJSONLWithState
- FlushManager now has true single ownership of flush state
- No more race conditions from concurrent global state access
- flushToJSONLWithState trusts only the flushState parameter
- Legacy wrapper handles success detection via failure count
2. Fix shutdown timeout data loss risk
- Increased timeout from 5s → 30s to prevent data loss
- Added detailed comments explaining the timeout rationale
- Better error message indicates potential data loss scenario
Implementation details:
- New FlushManager uses event-driven single-owner pattern
- Channels eliminate shared mutable state (markDirtyCh, flushNowCh, etc.)
- Comprehensive race detector tests verify concurrency safety
- Backward compatible with existing tests via legacy code path
- ARCHITECTURE.md documents design principles and guarantees
Test results:
- All race detector tests pass (TestFlushManager*)
- Legacy API compatibility verified (TestMarkDirtyAndScheduleFlush*)
- No race conditions detected under concurrent load
Future improvements tracked as beads:
- bd-gdn: Add functional tests for flush correctness verification
- bd-5xt: Log errors from timer-triggered flushes
- bd-i00: Convert magic numbers to named constants
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- bd-1h8: Add --no-daemon hint to compact error messages
- bd-8ql: Replace non-existent merge command with actionable guidance
- bd-ayw: Add 'When to use daemon mode' decision tree to daemon.md
- bd-keb: Add database maintenance section to QUICKSTART.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- docs/AGENT_MAIL_DEPLOYMENT.md: 10-step deployment plan for 13 workspaces
- docs/AGENT_MAIL_MULTI_WORKSPACE_SETUP.md: Architecture and configuration guide
- scripts/setup-agent-mail-workspace.sh: Auto-configure .envrc per workspace
- scripts/start-agent-mail-server.sh: Start Agent Mail server
- scripts/stop-agent-mail-server.sh: Stop Agent Mail server
- scripts/agent-mail-status.sh: Monitor server and all channels
Supports 3-channel setup: beads.dev, vc.dev, wyvern.dev
Ready for 0.23.0 deployment with Agent Mail integration
Amp-Thread-ID: https://ampcode.com/threads/T-bc960efb-3ddc-4635-8c8e-a42a6e9e67d9
Co-authored-by: Amp <amp@ampcode.com>
- Add AGENT_MAIL_QUICKSTART.md: 5-minute setup guide
- Add examples/python-agent/AGENT_MAIL_EXAMPLE.md: working code examples
- Add examples/python-agent/agent_with_mail.py: runnable multi-agent demo
- Update README.md: add Agent Mail to features and docs index
- Update AGENTS.md: enhance with quickstart/example references
- Update examples README: add Agent Mail example to index
Amp-Thread-ID: https://ampcode.com/threads/T-5d5e711d-7b5f-42ca-b75a-5b6cd843ad98
Co-authored-by: Amp <amp@ampcode.com>
- Installation and quick start
- Architecture and coordination flow
- Configuration reference (environment variables)
- When to use vs skip Agent Mail
- Multi-machine deployment patterns
- Troubleshooting and FAQ
- Migration guide from git-only mode
Closes bd-xzrv
Amp-Thread-ID: https://ampcode.com/threads/T-e8cf1b4b-38ae-4f6b-ae17-8b960d31608e
Co-authored-by: Amp <amp@ampcode.com>
- Created lib/beads_mail_adapter.py with AgentMailAdapter class
- Automatic health check on initialization
- Graceful degradation when server unavailable
- Methods: reserve_issue(), release_issue(), notify(), check_inbox()
- Environment-based configuration (AGENT_MAIL_URL, AGENT_MAIL_TOKEN)
- Comprehensive unit tests (15 tests, 100% passing)
- Full documentation in lib/README.md
Closes bd-m9th
Amp-Thread-ID: https://ampcode.com/threads/T-caa26228-0d18-4b35-b98a-9f95f6a099fe
Co-authored-by: Amp <amp@ampcode.com>
* fix: Use correct SQLite driver name 'sqlite3' instead of 'sqlite'
The ncruces/go-sqlite3 driver registers as 'sqlite3', but doctor.go
and example code were using 'sqlite', causing 'unknown driver' errors.
This fix corrects all sql.Open() calls to use the proper driver name:
- cmd/bd/doctor.go: 6 instances fixed
- docs/EXTENDING.md: 2 documentation examples updated
- examples/bd-example-extension-go/: Fixed example code and README
Fixes#230
Amp-Thread-ID: https://ampcode.com/threads/T-1e8c5473-cb79-4457-be07-4517bfdb73f4
Co-authored-by: Amp <amp@ampcode.com>
* Revert CGO_ENABLED back to 0 for pure-Go SQLite driver
The ncruces/go-sqlite3 driver is pure-Go and doesn't require CGO.
The previous change to CGO_ENABLED=1 in commit f9771cd was an
attempted fix for #230, but the real issue was the driver name
mismatch ('sqlite' vs 'sqlite3'), which is now fixed.
Benefits of CGO_ENABLED=0:
- Simpler cross-compilation (no C toolchain required)
- Smaller binaries
- Faster builds
- Matches the intended design of the pure-Go driver
---------
Co-authored-by: Amp <amp@ampcode.com>
* bd sync: 2025-10-30 12:12:27
* Working on frontend
* bd sync: 2025-11-06 16:55:55
* feat: finish bd monitor human viewer
* Merge conflicts resolved and added tests
* bd sync: 2025-11-06 17:23:41
* bd sync: 2025-11-06 17:34:52
* feat: Add reload button and multiselect status filter to monitor
- Changed status filter from single select to multiselect with 'Open' selected by default
- Added reload button with visual feedback (hover/active states)
- Updated filterIssues() to handle multiple selected statuses
- Added reloadData() function that reloads both stats and issues
- Improved responsive design for mobile devices
- Filter controls now use flexbox layout with better spacing
* fix: Update monitor statistics to show Total, In Progress, Open, Closed
- Replaced 'Ready to Work' stat with 'In Progress' stat
- Reordered stats to show logical progression: Total -> In Progress -> Open -> Closed
- Updated loadStats() to fetch in-progress count from stats API
- Removed unnecessary separate API call for ready count
* fix: Correct API field names in monitor stats JavaScript
The JavaScript was using incorrect field names (stats.total, stats.by_status)
that don't match the actual types.Statistics struct which uses flat fields
with underscores (total_issues, in_progress_issues, etc).
Fixed by updating loadStats() to use correct field names:
- stats.total -> stats.total_issues
- stats.by_status?.['in-progress'] -> stats.in_progress_issues
- stats.by_status?.open -> stats.open_issues
- stats.by_status?.closed -> stats.closed_issues
Fixes beads-9
* bd sync: 2025-11-06 17:51:24
* bd sync: 2025-11-06 17:56:09
* fix: Make monitor require daemon to prevent SQLite locking
Implemented Option 1 from beads-eel: monitor now requires daemon and never
opens direct SQLite connection.
Changes:
- Added 'monitor' to noDbCommands list in main.go to skip normal DB initialization
- Added validateDaemonForMonitor() PreRun function that:
- Finds database path using beads.FindDatabasePath()
- Validates daemon is running and healthy
- Fails gracefully with clear error message if no daemon
- Only uses RPC connection, never opens SQLite directly
Benefits:
- Eliminates SQLite locking conflicts between monitor and daemon
- Users can now close/update issues via CLI while monitor runs
- Clear error messages guide users to start daemon first
Fixes beads-eel
* bd sync: 2025-11-06 18:03:50
* docs: Add bd daemons restart subcommand documentation
Added documentation for the 'bd daemons restart' subcommand across all documentation files:
- commands/daemons.md: Added full restart subcommand section with synopsis, description, arguments, flags, and examples
- README.md: Added restart examples to daemon management section
- AGENTS.md: Added restart examples with --json flag for agents
The restart command gracefully stops and starts a specific daemon by workspace path or PID,
useful after upgrading bd or when a daemon needs refreshing.
Fixes beads-11
* bd sync: 2025-11-06 18:13:16
* Separated the web ui from the general monitoring functionality
---------
Co-authored-by: Steve Yegge <stevey@sourcegraph.com>
- Created migrations/ subdirectory with 14 individual migration files
- Reduced migrations.go from 680 to 98 lines (orchestration only)
- Updated test imports to use migrations package
- Updated MULTI_REPO_HYDRATION.md documentation
- All tests passing
- Created comprehensive migration guide at docs/MULTI_REPO_MIGRATION.md
- Covers OSS contributor, team, multi-phase, and persona workflows
- Step-by-step setup instructions with examples
- Configuration reference and troubleshooting
- Implemented bd migrate-issues command
- Move issues between repos with filtering (status/priority/labels/type)
- Dependency preservation with upstream/downstream/closure options
- Dry-run mode and strict validation
- Interactive confirmation with --yes override
- Updated README.md and AGENTS.md with migration guide links
Completes: bd-c3ei, bd-mlcz
Part of epic: bd-8rd (Migration and onboarding for multi-repo)
Amp-Thread-ID: https://ampcode.com/threads/T-c5a7a780-b05e-4cc3-a7c1-5de107821b7e
Co-authored-by: Amp <amp@ampcode.com>
- Add repo_mtimes table to track JSONL file modification times
- Implement HydrateFromMultiRepo() with mtime-based skip optimization
- Support tilde expansion for repo paths in config
- Add source_repo column via migration (not in base schema)
- Fix schema to allow migration on existing databases
- Comprehensive test coverage for hydration logic
- Resurrect missing parent issues bd-cb64c226 and bd-cbed9619
Implementation:
- internal/storage/sqlite/multirepo.go - Core hydration logic
- internal/storage/sqlite/multirepo_test.go - Test coverage
- docs/MULTI_REPO_HYDRATION.md - Documentation
Schema changes:
- source_repo column added via migration only (not base schema)
- repo_mtimes table for mtime caching
- All SELECT queries updated to include source_repo
Database recovery:
- Restored from 17 to 285 issues
- Created placeholder parents for orphaned hierarchical children
Amp-Thread-ID: https://ampcode.com/threads/T-faa1339a-14b2-426c-8e18-aa8be6f5cde6
Co-authored-by: Amp <amp@ampcode.com>
