- 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 test_agent_race.py with 3 test scenarios
- Tests collision prevention with Agent Mail reservations
- Validates that only one agent claims an issue when reservations active
- Demonstrates collision problem when Agent Mail disabled
- Includes stress test with 10 agents
- Non-interactive mode support for CI/automation
Amp-Thread-ID: https://ampcode.com/threads/T-2fb10899-490f-4d41-b003-8bc4d467cc54
Co-authored-by: Amp <amp@ampcode.com>
- Detect uncommitted changes in .beads/issues.jsonl
- Warn users when database matches working tree but differs from git HEAD
- Clarify import status messages (working tree vs git sync)
- Add comprehensive tests for dirty working tree scenarios
- Prevents false confidence about sync status
Amp-Thread-ID: https://ampcode.com/threads/T-5a0f1045-a690-42ef-8bfc-f8cf30ee4084
Co-authored-by: Amp <amp@ampcode.com>
- bd-27xm: Mark as external debugging work
- Updated status doc to emphasize separation
- Agent Mail server at ~/src/mcp_agent_mail (separate repo)
- Beads integration will be lightweight HTTP client only
Implements bd-jx90: simple cleanup command without API key requirement.
Features:
- Delete all closed issues with --force
- Filter by age with --older-than N (days)
- Preview with --dry-run
- Cascade deletion with --cascade
- JSON output support
Usage:
bd cleanup --force # Delete all closed
bd cleanup --older-than 30 --force # Delete >30 days old
bd cleanup --dry-run # Preview
Closes bd-jx90
Amp-Thread-ID: https://ampcode.com/threads/T-8d905db0-4ec7-411e-95de-1f044219dc9c
Co-authored-by: Amp <amp@ampcode.com>
- Add BD_RPC_DEBUG=1 for lightweight timing logs to stderr
- Log socket path, socket exists check, dial timing, health check timing
- Improve daemon status message when lock not held
- Helps field triage of connection issues without verbose daemon logs
- Fixes bd-j7e2
- Changed TryConnect default from 2s to 200ms
- Updated fallback timeout in TryConnectWithTimeout
- Complements bd-wgu4 lock probe to eliminate 5s delays
- Fixes GH#243 (5s delay when daemon socket missing)
- Health checks still use longer timeouts via explicit TryConnectWithTimeout calls
Prevents data loss when exporting stale database by comparing issue IDs,
not just counts. Detects both scenarios:
- Database has fewer issues than JSONL
- Database has different issues than JSONL (same count)
Shows specific missing issue IDs in error. Allows override with --force.
Includes comprehensive tests for all scenarios.
bd export currently silently overwrites issues.jsonl even when the
database is stale (older than the JSONL file). This causes data loss
in multi-agent workflows.
Real incident from vc project:
- Agent A created 4 discovery epics and exported
- Agent B had stale database and exported, removing those epics
- Required manual recovery
Proposed fix: Check database freshness before export, similar to
VC's ValidateDatabaseFreshness(). Require --force to override.
Priority P1: Silent data loss in common multi-agent scenario.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix BdCliClient._run_command() to pass BEADS_DIR/BEADS_DB env vars to subprocess
- Update temp_db fixture to create .beads in workspace and return .beads dir path
- Update mcp_client fixture to use beads_dir and enable BEADS_NO_DAEMON mode
- Simplify test_init_tool to work with connection pool architecture
Result: All 19 integration tests now pass (was 19 failing)
Amp-Thread-ID: https://ampcode.com/threads/T-c1da2a55-f086-4284-9c85-0dfa4c479cf9
Co-authored-by: Amp <amp@ampcode.com>
- Update tests to use issue_id/depends_on_id instead of from_id/to_id
- Fix test_client_lazy_initialization to mock create_bd_client instead of BdClient
- Add workspace setup for lazy initialization test
- Fixes 2 test failures (now 123 passing, down from 121)
Amp-Thread-ID: https://ampcode.com/threads/T-71b3ce65-87cb-451a-a30d-162d76d92f9c
Co-authored-by: Amp <amp@ampcode.com>
- Add shell=True for subprocess.run() on Windows platform
- Improves git command PATH resolution on Windows
- Add debug logging for git detection failures
- Fixes GH#245 timeout issue where git rev-parse times out in MCP server
Amp-Thread-ID: https://ampcode.com/threads/T-71b3ce65-87cb-451a-a30d-162d76d92f9c
Co-authored-by: Amp <amp@ampcode.com>
