Prevent user confusion when running outdated bd binaries by detecting
version mismatches between the binary and database.
Features:
- Store bd version in metadata table on init
- Check version on every command (PersistentPreRun)
- Warn if binary is outdated with rebuild instructions
- Auto-upgrade database if binary is newer
- Silent operation when versions match
Fixes confusion from bd-182 (auto-export not working with old binary)
Implements bd-197
Files changed:
- cmd/bd/init.go: Store version on init
- cmd/bd/main.go: checkVersionMismatch() + integration
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The plugin documentation now explicitly states that:
1. The bd CLI must be installed first (prerequisite)
2. Plugin installation is a multi-step process (marketplace add + install + restart)
3. Removed misleading 'one-command' and 'auto-configured' language
This completes the documentation fixes started in PR #35.
The README was claiming one-command, zero-config installation, but actually requires: 1) marketplace add, 2) plugin install, 3) separate bd CLI installation. This revert tones down the promotional language to match reality.
Thanks to @jjshanks for catching this!
When GetStatistics is called on an empty database, SQL SUM() returns NULL
which causes a scan error when converting to int. Wrap SUM expressions with
COALESCE to return 0 instead of NULL.
Add TestGetStatistics to verify both empty and populated database cases.
Fixes issue where `bd stats` and MCP stats tool crash on fresh databases.
Signed-off-by: Joshua Shanks <jjshanks@gmail.com>
- Add idx_dependencies_depends_on_type index on (depends_on_id, type)
- Optimize queries filtering by both target issue and dependency type
- Improve performance for dep tree and relationship queries
- Update plugin version to 0.9.5
- Sync issue database
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added a debug tool that reports:
- os.getcwd() value
- PWD environment variable
- BEADS_WORKING_DIR environment variable
- Other relevant environment variables
This will help diagnose where bd commands are running from and whether
Claude Code sets PWD or other variables correctly.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove TESTING_NEXT.md (content tracked in bd-64)
- Remove .beads/bd-9-design.md (designs belong in issue design field)
- Update DESIGN.md: replace Implementation Roadmap with pointer to bd list
- All work tracking now in beads database, not markdown files
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The MCP server was running bd commands from the plugin installation directory,
causing the database to be created in the wrong place.
Added BEADS_WORKING_DIR config option and modified BdClient to use working
directory for subprocess calls. Falls back to PWD environment variable.
This ensures bd commands run from the user's actual project directory.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Added clear installation instructions for users of Sourcegraph Amp, Claude Desktop,
and other MCP clients right after the Claude Code plugin section.
Users can now easily find instructions to install via:
- uv tool install beads-mcp
- pip install beads-mcp
Includes Claude Desktop configuration example and link to detailed MCP server docs.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Prepared the beads-mcp package for publishing to PyPI, simplifying installation
for users who want to use the MCP server with Claude Desktop or other MCP clients.
Changes:
- Added LICENSE file (MIT) to integrations/beads-mcp/
- Updated pyproject.toml with PyPI metadata (license, URLs, classifiers)
- Updated README with simplified installation (uv tool install beads-mcp)
- Created PYPI.md with detailed publishing guide
- Updated examples/claude-desktop-mcp/README to reference the production MCP server
Installation is now simplified from:
git clone && cd && uv sync
to:
uv tool install beads-mcp
Configuration is simplified from multi-line with --directory args to:
"command": "beads-mcp"
Tested build successfully. Package ready for:
- Test PyPI: python -m twine upload --repository testpypi dist/*
- Production PyPI: python -m twine upload dist/*
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add helpful installation instructions when bd CLI is not found,
making it clear that the CLI must be installed separately.
Changes:
- Add BdNotFoundError.installation_message() with clear install steps
- Update all BdNotFoundError raises to use new formatted message
- Improve config error message with installation instructions first
- Update tests to match new error message format
Error message now shows:
- Clear explanation that bd CLI is required
- Installation command with curl one-liner
- Link to GitHub installation docs
- Reminder to restart Claude Code after installation
Test results: 90/91 tests passing (1 unrelated path assertion)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Hook automatically rebuilds and installs bd CLI when Go files change.
Usage in new clones:
./scripts/install-hooks.sh
Files:
- scripts/hooks/post-push: Hook that runs go install after successful push
- scripts/install-hooks.sh: Installer to set up hooks in new clones
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The MCP server was running all bd commands in its own installation directory
(~/.claude/plugins/marketplaces/beads-marketplace/integrations/beads-mcp/)
instead of the user's project directory. This caused databases to be created
in the wrong location.
For example, when working in ~/ai/flutter/wyvern and running `bd init --prefix wy-`,
the database was created at:
~/.claude/plugins/marketplaces/beads-marketplace/integrations/beads-mcp/.beads/wy-.db
Instead of the expected location:
~/ai/flutter/wyvern/.beads/wy-.db
Solution:
- Add `cwd=os.getcwd()` to all asyncio.create_subprocess_exec() calls
- This makes bd commands execute in the current working directory from PWD env var
- Claude Code updates PWD for the MCP server process environment
Impact:
- bd init now creates .beads/ in the correct project directory
- All bd commands (create, list, update, etc.) operate on the correct database
- Multi-project workflows work correctly without manual DB path configuration
Test results: 90/91 tests passing (1 unrelated path assertion failure)
Critical bug: MCP init tool reported success but didn't create .beads
directory. It was using --db flag which tells bd to use an existing
database elsewhere instead of creating a new one.
Root cause:
- bd_client.init() was calling _global_flags() which adds --db flag
- bd init --db <path> uses existing db instead of creating new one
- Result: init appeared to succeed but created nothing
Fix:
- Remove _global_flags() from init command
- Only pass --actor flag (safe for init)
- Do NOT pass --db flag to init (defeats the purpose)
- Add explicit comment explaining why
Testing:
- Added test_init_creates_beads_directory() integration test
- Verifies .beads directory is created in current working directory
- Verifies database file has correct prefix
- All 91 tests pass
This was causing silent failures where agents thought they initialized
bd but the .beads directory was never created.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Make it clearer that the Claude Code plugin is the recommended
installation method for Claude Code users.
Changes:
- Add Claude Code plugin option to "Instant start" section at top
- Expand plugin benefits (zero setup, MCP tools, agent-ready)
- List example MCP tool names for agents
- Clarify that agents can use MCP directly vs Bash commands
This addresses the issue where agents didn't know they could use
the MCP tools and were falling back to Bash commands instead.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes issue where MCP tools failed with "bd executable not found"
when BEADS_PATH was set to command name instead of absolute path.
Changes:
- Remove BEADS_PATH=bd from plugin.json (use auto-detection)
- Enhance config validator to resolve command names via PATH
- Add comprehensive config validation tests (11 new tests)
The validator now accepts both:
- Absolute paths: /usr/local/bin/bd
- Command names: bd (resolved via shutil.which)
This makes the MCP server more robust and user-friendly while
maintaining backward compatibility.
All 90 tests pass.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Ensures exactly one hyphen between prefix and issue number regardless of
whether user provides trailing hyphen.
Before:
bd init --prefix wy- → Issues: wy--1, wy--2 (double hyphen)
bd init --prefix wy → Issues: wy-1, wy-2 (single hyphen)
After:
bd init --prefix wy- → Issues: wy-1, wy-2 (single hyphen)
bd init --prefix wy → Issues: wy-1, wy-2 (single hyphen)
The hyphen is added automatically during ID generation in CreateIssue(),
so the stored prefix should never include trailing hyphens.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes MCP server hanging when bd executable is not found at default path.
Problem:
- Config validation used sys.exit(1) on failure
- sys.exit() hangs in async MCP server context (doesn't properly terminate)
- Default bd path was hardcoded to ~/.local/bin/bd
Solution:
1. Use shutil.which() to find bd in PATH before falling back to default
2. Raise ConfigError instead of calling sys.exit()
3. MCP server now properly fails with error message instead of hanging
This fixes the multi-minute hang when trying to use MCP tools if bd is
installed in a non-default location (e.g., /usr/local/bin/bd).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Allow users to specify a custom issue prefix when initializing beads:
/bd-init myproject
If no prefix is provided, defaults to current directory name (existing behavior).
Changes:
- Add argument-hint: [prefix] to command frontmatter
- Update command description to document $1 parameter usage
- Pass prefix to MCP init tool when provided
The MCP init tool already supported the prefix parameter, this just
exposes it through the slash command interface.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes Claude Code marketplace plugin installation failure (bd-183).
Problem: The plugin.json manifest included an engines field (borrowed from npm)
to specify minimum bd CLI version requirements. However, Claude Code's plugin
manifest schema doesn't recognize this field, causing validation errors when
installing via /plugin marketplace add.
Solution:
1. Remove the engines field from plugin.json
2. Add runtime version checking in the MCP server startup
3. Update documentation to reflect automatic version checking
Changes:
- .claude-plugin/plugin.json: Remove unsupported engines field
- integrations/beads-mcp/src/beads_mcp/bd_client.py:
- Add BdVersionError exception class
- Add _check_version() method to validate bd CLI >= 0.9.0
- Use bd version command (not bd --version)
- integrations/beads-mcp/src/beads_mcp/tools.py:
- Make _get_client() async to support version checking
- Update all tool functions to await _get_client()
- Add version check on first MCP server use
- .claude-plugin/commands/bd-version.md: Update to mention automatic checking
- PLUGIN.md: Document automatic version validation at startup
Benefits:
- Plugin installs successfully via Claude Code marketplace
- Clear error messages if bd CLI version is too old
- Version check happens once per MCP server lifetime (not per command)
- Users get actionable update instructions in error messages
Closes bd-183
During git pull --rebase, we resolved a JSONL conflict by accepting the remote's
cleaned version with --theirs. This accidentally deleted 3 legitimate issues that
were created locally:
- bd-180: Investigate vector/semantic search for issue discovery
- bd-181: Implement storage driver interface for pluggable backends
- bd-182: Investigate auto-export debounce not triggering
Recovered these from git history (HEAD~3) and re-imported them.
Stats: 72 → 75 issues (3 recovered)
Issue found: bump-version.sh was missing the MCP server's __init__.py file, causing version mismatches (pyproject.toml: 0.9.2, __init__.py: 1.0.0).
Changes:
- Add integrations/beads-mcp/src/beads_mcp/__init__.py to update list
- Add it to git staging in auto-commit
- Add it to verification check
- Fix current version mismatch: 1.0.0 to 0.9.2
Now the script updates 7 files instead of 6
**CI Improvements:**
- Fix Go version: 1.25 → 1.23 (matches go.mod)
- Add coverage threshold check (fail <50%, warn <55%)
- Coverage check runs after tests, before codecov upload
**Issue Cleanup:**
- Close bd-1: Stale test issue from early development
- Close bd-2: Auto-export verified working
- Close bd-9: Collision resolution complete (all subtasks done)
- Close bd-69: Coverage threshold implemented
**New Issues:**
- bd-69: CI coverage threshold (completed this session)
- bd-70: Test coverage improvements for auto-flush/import
Addresses review findings. System is now clean and ready for plugin testing (bd-64).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The codebase had two identical JSONL files (bd.jsonl and issues.jsonl).
The code defaults to issues.jsonl but FindJSONLPath() would pick bd.jsonl
alphabetically. Removed the duplicate to use only the standard filename.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Creates TESTING_NEXT.md with complete context for next agent to test
the Claude Code plugin from GitHub.
Includes:
- What was completed this session
- Detailed testing instructions
- Potential issues to watch for
- Important files and commit references
- Success criteria
- How to continue based on test results
This ensures no context is lost between sessions and the next agent
knows exactly what to do (test plugin from GitHub).
Related: bd-64 (plugin testing task)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds prominent section explaining how to bump versions using the new
script. Future AI agents will know to use ./scripts/bump-version.sh
when the user requests a version bump.
Includes:
- Common user phrases for version bumps
- Step-by-step instructions
- What files get updated automatically
- Why this matters (references bd-66 issue)
Also updates Release Process section to use the script.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Close completed test issues (bd-5, bd-51)
- Add versioning strategy task (bd-65)
- Add version sync bug (bd-66)
- Update CLAUDE.md to reflect MCP server implementation status
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds scripts/bump-version.sh to automate version syncing across all
beads components, preventing version mismatches like bd-66.
Features:
- Updates all version files in one command
- Validates semantic versioning format
- Verifies all versions match after update
- Shows git diff preview
- Optional auto-commit with standardized message
- Cross-platform compatible (macOS/Linux)
Files updated by script:
- cmd/bd/version.go
- .claude-plugin/plugin.json
- .claude-plugin/marketplace.json
- integrations/beads-mcp/pyproject.toml
- README.md
- PLUGIN.md
Usage:
./scripts/bump-version.sh 0.9.3 # Dry run with diff
./scripts/bump-version.sh 0.9.3 --commit # Auto-commit
Closes bd-67
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes version inconsistencies across the project. All components now at 0.9.2:
Updated:
- .claude-plugin/plugin.json: 0.9.0 → 0.9.2
- .claude-plugin/marketplace.json: 0.9.0 → 0.9.2
- integrations/beads-mcp/pyproject.toml: 1.0.0 → 0.9.2
- README.md: v0.9.0 → v0.9.2
- PLUGIN.md: Updated version requirements
Root cause: Previous version bumps (0.9.0 → 0.9.1 → 0.9.2) only updated
cmd/bd/version.go, leaving other components out of sync.
The MCP server was initially versioned at 1.0.0 when added today, but
syncing to 0.9.2 for consistency since the project is still in alpha.
Closes bd-66
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds version management to help users keep bd CLI and plugin in sync.
Changes:
- Add engines field to plugin.json requiring bd >=0.9.0
- Add /bd-version command to check component versions
- Add comprehensive "Updating" section to PLUGIN.md
- Document recommended update workflow
Users can now run /bd-version to check:
- bd CLI version
- Plugin version
- MCP server status
- Compatibility warnings
Addresses version sync concerns raised in plugin development.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add lightweight example script for converting markdown planning docs
to bd JSONL format. This addresses #9 without adding complexity to
bd core.
Features:
- YAML frontmatter parsing (priority, type, assignee)
- Headings converted to issues
- Task lists extracted as sub-issues
- Dependency parsing (blocks: bd-10, etc.)
- Fully customizable by users
This demonstrates the "lightweight extension pattern" - keeping bd
core minimal while providing examples users can adapt for their needs.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement `bd create -f file.md` to parse markdown files and create
multiple issues in one command. This enables drafting features in
markdown and converting them to tracked issues.
Features:
- Parse markdown H2 headers (##) as issue titles
- Support all issue fields via H3 sections (### Priority, ### Type, etc.)
- Handle multiple issues per file
- Comprehensive validation and error handling
- Full test coverage with 5 test cases
Closes bd-91 (GH-9)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add "Hierarchical Blocking" section to README explaining blocking propagation through parent-child hierarchies
- Clarify that 'blocks' + 'parent-child' create transitive blocking up to 50 levels deep
- Note that 'related' and 'discovered-from' do NOT propagate blocking
- Add TestDeepHierarchyBlocking to verify 50-level deep hierarchy works correctly
- All tests pass successfully
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The ready_issues VIEW was using old logic that didn't propagate blocking
through parent-child hierarchies. This caused inconsistency with the
GetReadyWork() function for users querying via sqlite3 CLI.
Changes:
- Updated VIEW to use same recursive CTE as GetReadyWork()
- Added test to verify VIEW and function produce identical results
- No migration needed (CREATE VIEW IF NOT EXISTS handles recreation)
The VIEW is documented in WORKFLOW.md for direct SQL queries and is now
consistent with the function-based API.
Resolves: bd-60
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds a Claude Code plugin for one-command installation of beads via
/plugin command. The plugin bundles the MCP server, slash commands,
and an autonomous task agent.
Components:
- Plugin metadata with MCP server configuration
- 8 slash commands for core workflow (/bd-ready, /bd-create, etc.)
- Task agent for autonomous execution (@task-agent)
- Comprehensive plugin documentation (PLUGIN.md)
The plugin provides a lower-friction installation path for Claude Code
users who want integrated slash commands rather than direct MCP tools.
Related: https://github.com/steveyegge/beads/issues/28🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The hierarchical blocking query recursively joins on dependencies with
a type filter. Without a composite index, SQLite must scan all
dependencies for a given depends_on_id and filter by type afterward.
With 10k+ issues and many dependencies per issue, this could cause
noticeable slowdowns in ready work calculations.
Changes:
- Added idx_dependencies_depends_on_type composite index to schema
- Added automatic migration for existing databases
- Index creation is silent and requires no user intervention
The recursive CTE now efficiently seeks (depends_on_id, type) pairs
directly instead of post-filtering.
Resolves: bd-59
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
