johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bd sync: 2025-11-26 18:07:01

Browse Source
This commit is contained in:
Steve Yegge
2025-11-26 18:07:01 -08:00
parent daa94e5b31
commit eeda2053b8
6 changed files with 130 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.beads/beads.jsonl
View File

@@ -43,7 +43,7 @@
{"id":"bd-tru","title":"Update documentation for bd prime and Claude integration","description":"Update AGENTS.md, README.md, and QUICKSTART.md to document the new `bd prime` command, `bd setup claude` command, and tip system.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-11T23:30:22.77349-08:00","updated_at":"2025-11-25T17:47:30.807069-08:00","closed_at":"2025-11-25T17:47:30.807069-08:00"} {"id":"bd-tru","title":"Update documentation for bd prime and Claude integration","description":"Update AGENTS.md, README.md, and QUICKSTART.md to document the new `bd prime` command, `bd setup claude` command, and tip system.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-11T23:30:22.77349-08:00","updated_at":"2025-11-25T17:47:30.807069-08:00","closed_at":"2025-11-25T17:47:30.807069-08:00"}
{"id":"bd-tys","title":"Git history fallback has incorrect logic for detecting deletions","description":"## Problem\n\nThe `wasInGitHistory` function in `internal/importer/importer.go:891` returns true if the ID is found **anywhere** in git history. But finding an ID in history doesn't necessarily mean it was deleted - it could mean:\n\n1. The issue was added (appears in a commit adding it)\n2. The issue was modified (appears in commits updating it)\n3. The issue was deleted (appears in a commit removing it)\n\nThe current logic incorrectly treats all three cases as 'deleted'.\n\n## Correct Logic\n\n`git log -S` with `--oneline` shows commits where the string was added OR removed. To detect deletion specifically:\n\n1. ID appears in git history (was once in JSONL)\n2. ID is NOT currently in JSONL\n\nThe second condition is already checked by the caller (`purgeDeletedIssues`), so technically the logic is correct in context. But the function name and doc comment are misleading.\n\n## Fix Options\n\n1. **Rename function** to `wasEverInJSONL` and update doc comment to clarify\n2. **Add explicit check** for current JSONL state in the function itself\n\nOption 1 is simpler and correct since caller already filters.","status":"closed","priority":3,"issue_type":"bug","created_at":"2025-11-25T12:46:16.073661-08:00","updated_at":"2025-11-25T15:11:54.426093-08:00","closed_at":"2025-11-25T15:11:54.426093-08:00"} {"id":"bd-tys","title":"Git history fallback has incorrect logic for detecting deletions","description":"## Problem\n\nThe `wasInGitHistory` function in `internal/importer/importer.go:891` returns true if the ID is found **anywhere** in git history. But finding an ID in history doesn't necessarily mean it was deleted - it could mean:\n\n1. The issue was added (appears in a commit adding it)\n2. The issue was modified (appears in commits updating it)\n3. The issue was deleted (appears in a commit removing it)\n\nThe current logic incorrectly treats all three cases as 'deleted'.\n\n## Correct Logic\n\n`git log -S` with `--oneline` shows commits where the string was added OR removed. To detect deletion specifically:\n\n1. ID appears in git history (was once in JSONL)\n2. ID is NOT currently in JSONL\n\nThe second condition is already checked by the caller (`purgeDeletedIssues`), so technically the logic is correct in context. But the function name and doc comment are misleading.\n\n## Fix Options\n\n1. **Rename function** to `wasEverInJSONL` and update doc comment to clarify\n2. **Add explicit check** for current JSONL state in the function itself\n\nOption 1 is simpler and correct since caller already filters.","status":"closed","priority":3,"issue_type":"bug","created_at":"2025-11-25T12:46:16.073661-08:00","updated_at":"2025-11-25T15:11:54.426093-08:00","closed_at":"2025-11-25T15:11:54.426093-08:00"}
{"id":"bd-v29","title":"Deletions pruning doesn't include results in JSON output","description":"## Problem\n\nWhen `bd compact --json` runs with deletions pruning, the prune results are silently discarded:\n\n```go\n// Only report if there were deletions to prune\nif result.PrunedCount \u003e 0 {\n if jsonOutput {\n // JSON output will be included in the main response\n return // \u003c-- BUG: results are NOT included anywhere\n }\n ...\n}\n```\n\n## Location\n`cmd/bd/compact.go:925-929`\n\n## Impact\n- JSON consumers don't know deletions were pruned\n- No way to audit pruning via automation\n\n## Fix\nReturn prune results and include in JSON output structure:\n\n```json\n{\n \"success\": true,\n \"compacted\": {...},\n \"deletions_pruned\": {\n \"count\": 5,\n \"retention_days\": 7\n }\n}\n```","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-25T12:48:59.730979-08:00","updated_at":"2025-11-25T15:11:54.363653-08:00","closed_at":"2025-11-25T15:11:54.363653-08:00"} {"id":"bd-v29","title":"Deletions pruning doesn't include results in JSON output","description":"## Problem\n\nWhen `bd compact --json` runs with deletions pruning, the prune results are silently discarded:\n\n```go\n// Only report if there were deletions to prune\nif result.PrunedCount \u003e 0 {\n if jsonOutput {\n // JSON output will be included in the main response\n return // \u003c-- BUG: results are NOT included anywhere\n }\n ...\n}\n```\n\n## Location\n`cmd/bd/compact.go:925-929`\n\n## Impact\n- JSON consumers don't know deletions were pruned\n- No way to audit pruning via automation\n\n## Fix\nReturn prune results and include in JSON output structure:\n\n```json\n{\n \"success\": true,\n \"compacted\": {...},\n \"deletions_pruned\": {\n \"count\": 5,\n \"retention_days\": 7\n }\n}\n```","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-25T12:48:59.730979-08:00","updated_at":"2025-11-25T15:11:54.363653-08:00","closed_at":"2025-11-25T15:11:54.363653-08:00"}
{"id":"bd-wcl","title":"Document CLI + hooks as recommended approach over MCP","description":"Update documentation to position CLI + bd prime hooks as the primary recommended approach over MCP server, explaining why minimizing context matters even with large context windows (compute cost, energy, environment, latency).","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-12T00:15:25.923025-08:00","updated_at":"2025-11-12T00:18:16.786857-08:00"} {"id":"bd-wcl","title":"Document CLI + hooks as recommended approach over MCP","description":"Update documentation to position CLI + bd prime hooks as the primary recommended approach over MCP server, explaining why minimizing context matters even with large context windows (compute cost, energy, environment, latency).","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-12T00:15:25.923025-08:00","updated_at":"2025-11-26T18:06:51.020351-08:00","closed_at":"2025-11-26T18:06:51.020351-08:00"}
{"id":"bd-wmo","title":"PruneDeletions iterates map non-deterministically","description":"## Problem\n\n`PruneDeletions` iterates over `loadResult.Records` which is a map. Go maps iterate in random order, so:\n\n1. `result.PrunedIDs` order is non-deterministic\n2. `kept` slice order is non-deterministic → `WriteDeletions` output order varies\n\n## Location\n`internal/deletions/deletions.go:213`\n\n## Impact\n- Git diffs are noisy (file changes order on each prune)\n- Tests could be flaky if they depend on order\n- Harder to debug/audit\n\n## Fix\nSort by ID or timestamp before iterating:\n\n```go\n// Convert map to slice and sort\nvar records []DeletionRecord\nfor _, r := range loadResult.Records {\n records = append(records, r)\n}\nsort.Slice(records, func(i, j int) bool {\n return records[i].ID \u003c records[j].ID\n})\n```","status":"closed","priority":3,"issue_type":"bug","created_at":"2025-11-25T12:49:11.290916-08:00","updated_at":"2025-11-25T15:15:21.903649-08:00","closed_at":"2025-11-25T15:15:21.903649-08:00"} {"id":"bd-wmo","title":"PruneDeletions iterates map non-deterministically","description":"## Problem\n\n`PruneDeletions` iterates over `loadResult.Records` which is a map. Go maps iterate in random order, so:\n\n1. `result.PrunedIDs` order is non-deterministic\n2. `kept` slice order is non-deterministic → `WriteDeletions` output order varies\n\n## Location\n`internal/deletions/deletions.go:213`\n\n## Impact\n- Git diffs are noisy (file changes order on each prune)\n- Tests could be flaky if they depend on order\n- Harder to debug/audit\n\n## Fix\nSort by ID or timestamp before iterating:\n\n```go\n// Convert map to slice and sort\nvar records []DeletionRecord\nfor _, r := range loadResult.Records {\n records = append(records, r)\n}\nsort.Slice(records, func(i, j int) bool {\n return records[i].ID \u003c records[j].ID\n})\n```","status":"closed","priority":3,"issue_type":"bug","created_at":"2025-11-25T12:49:11.290916-08:00","updated_at":"2025-11-25T15:15:21.903649-08:00","closed_at":"2025-11-25T15:15:21.903649-08:00"}
{"id":"bd-x2i","title":"Add bd deleted command for audit trail","description":"Parent: bd-imj\n\nAdd command to view deletion history.\n\nUsage:\n bd deleted # Show recent deletions (last 7 days)\n bd deleted --since=30d # Show deletions in last 30 days\n bd deleted --all # Show all tracked deletions\n bd deleted bd-xxx # Show deletion details for specific issue\n\nOutput format:\n bd-xxx 2025-11-25 10:00 stevey duplicate of bd-yyy\n bd-yyy 2025-11-25 10:05 claude cleanup\n\nAcceptance criteria:\n- List deletions with timestamp, actor, reason\n- Filter by time range\n- Lookup specific issue ID\n- JSON output option for scripting","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T09:57:21.113861-08:00","updated_at":"2025-11-25T15:13:53.781519-08:00","closed_at":"2025-11-25T15:13:53.781519-08:00"} {"id":"bd-x2i","title":"Add bd deleted command for audit trail","description":"Parent: bd-imj\n\nAdd command to view deletion history.\n\nUsage:\n bd deleted # Show recent deletions (last 7 days)\n bd deleted --since=30d # Show deletions in last 30 days\n bd deleted --all # Show all tracked deletions\n bd deleted bd-xxx # Show deletion details for specific issue\n\nOutput format:\n bd-xxx 2025-11-25 10:00 stevey duplicate of bd-yyy\n bd-yyy 2025-11-25 10:05 claude cleanup\n\nAcceptance criteria:\n- List deletions with timestamp, actor, reason\n- Filter by time range\n- Lookup specific issue ID\n- JSON output option for scripting","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T09:57:21.113861-08:00","updated_at":"2025-11-25T15:13:53.781519-08:00","closed_at":"2025-11-25T15:13:53.781519-08:00"}
{"id":"bd-xyc","title":"Consolidate check-health DB opens into single connection","description":"The --check-health flag opens the database 3 separate times (once per quick check). Consolidate into a single DB open for better performance, especially on slower filesystems.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T19:27:42.034178-08:00","updated_at":"2025-11-25T19:50:21.32375-08:00","closed_at":"2025-11-25T19:50:21.32375-08:00"} {"id":"bd-xyc","title":"Consolidate check-health DB opens into single connection","description":"The --check-health flag opens the database 3 separate times (once per quick check). Consolidate into a single DB open for better performance, especially on slower filesystems.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T19:27:42.034178-08:00","updated_at":"2025-11-25T19:50:21.32375-08:00","closed_at":"2025-11-25T19:50:21.32375-08:00"}

174
AGENTS.md
View File

@@ -74,118 +74,45 @@ bd init --quiet # Non-interactive, auto-installs git hooks, no prompts
We use bd (beads) for issue tracking instead of Markdown TODOs or external tools. We use bd (beads) for issue tracking instead of Markdown TODOs or external tools.
### MCP Server (Recommended) ### CLI + Hooks (Recommended)
**RECOMMENDED**: Use the MCP (Model Context Protocol) server for the best experience! The beads MCP server provides native integration with Claude and other MCP-compatible AI assistants. **RECOMMENDED**: Use the `bd` CLI with hooks for the best experience. This approach:
**Installation:** - **Minimizes context usage** - Only injects ~1-2k tokens via `bd prime` vs MCP tool schemas
- **Reduces compute cost** - Less tokens = less processing per request
```bash - **Lower latency** - Direct CLI calls are faster than MCP protocol overhead
# Install the MCP server - **More sustainable** - Every token has compute/energy cost; lean prompts are greener
pip install beads-mcp - **Universal** - Works with any AI assistant, not just MCP-compatible ones
# Add to your MCP settings (e.g., Claude Desktop config)
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
```
**Benefits:**
- Native function calls instead of shell commands
- Automatic workspace detection
- Better error handling and validation
- Structured JSON responses
- No need for `--json` flags
**All bd commands are available as MCP functions** with the prefix `mcp__beads-*__`. For example:
- `bd ready` → `mcp__beads__ready()`
- `bd create` → `mcp__beads__create(title="...", priority=1)`
- `bd update` → `mcp__beads__update(issue_id="bd-42", status="in_progress")`
See `integrations/beads-mcp/README.md` for complete documentation.
### Multi-Repo Configuration (MCP Server)
**RECOMMENDED: Use a single MCP server for all beads projects** - it automatically routes to per-project local daemons.
**For AI agent multi-repo patterns**, see [docs/MULTI_REPO_AGENTS.md](docs/MULTI_REPO_AGENTS.md) (config options, routing, troubleshooting, best practices).
**For complete multi-repo workflow guide**, see [docs/MULTI_REPO_MIGRATION.md](docs/MULTI_REPO_MIGRATION.md) (OSS contributors, teams, multi-phase development).
**Setup (one-time):** **Setup (one-time):**
```bash ```bash
# MCP config in ~/.config/amp/settings.json or Claude Desktop config: # Install bd CLI (see docs/INSTALLING.md)
{ brew install bd # or other methods
"beads": {
"command": "beads-mcp", # Initialize in your project
"args": [] bd init --quiet
}
} # Install hooks for automatic context injection
bd hooks install
``` ```
**How it works (LSP model):** **How it works:**
The single MCP server instance automatically:
1. Checks for local daemon socket (`.beads/bd.sock`) in your current workspace 1. **SessionStart hook** runs `bd prime` automatically when Claude Code starts
2. Routes requests to the correct **per-project daemon** based on working directory 2. `bd prime` injects a compact workflow reference (~1-2k tokens)
3. Auto-starts the local daemon if not running (with exponential backoff) 3. You use `bd` CLI commands directly (no MCP layer needed)
4. **Each project gets its own isolated daemon** serving only its database 4. Git hooks auto-sync the database with JSONL
**Architecture:** **Why context minimization matters:**
``` Even with 200k+ context windows, minimizing context is important:
MCP Server (one instance) - **Compute cost scales with tokens** - More context = more expensive inference
↓ - **Latency increases with context** - Larger prompts take longer to process
Per-Project Daemons (one per workspace) - **Energy consumption** - Every token has environmental impact
↓ - **Attention quality** - Models attend better to smaller, focused contexts
SQLite Databases (complete isolation)
```
**Why per-project daemons?** A 50k token MCP schema consumes the same compute whether you use those tools or not. The CLI approach keeps your context lean and focused.
- ✅ Complete database isolation between projects
- ✅ No cross-project pollution or git worktree conflicts
- ✅ Simpler mental model: one project = one database = one daemon
- ✅ Follows LSP (Language Server Protocol) architecture
**Note:** The daemon **auto-starts automatically** when you run any `bd` command (v0.9.11+). To disable auto-start, set `BEADS_AUTO_START_DAEMON=false`.
**Version Management:** bd automatically handles daemon version mismatches (v0.16.0+):
- When you upgrade bd, old daemons are automatically detected and restarted
- Version compatibility is checked on every connection
- No manual intervention required after upgrades
- Works transparently with MCP server and CLI
- Use `bd daemons health` to check for version mismatches
- Use `bd daemons killall` to force-restart all daemons if needed
**Alternative (not recommended): Multiple MCP Server Instances**
If you must use separate MCP servers:
```json
{
"beads-webapp": {
"command": "beads-mcp",
"env": {
"BEADS_WORKING_DIR": "/Users/you/projects/webapp"
}
},
"beads-api": {
"command": "beads-mcp",
"env": {
"BEADS_WORKING_DIR": "/Users/you/projects/api"
}
}
}
```
⚠️ **Problem**: AI may select the wrong MCP server for your workspace, causing commands to operate on the wrong database.
### CLI Quick Reference ### CLI Quick Reference
@@ -213,6 +140,36 @@ bd sync # Force immediate export/commit/push
**For comprehensive CLI documentation**, see [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md). **For comprehensive CLI documentation**, see [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md).
### MCP Server (Alternative)
For Claude Desktop, Sourcegraph Amp, or other MCP-only environments where CLI access is limited, use the MCP server:
```bash
pip install beads-mcp
```
Add to MCP config:
```json
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
```
**When to use MCP:**
- ✅ Claude Desktop (no shell access)
- ✅ MCP-only environments
- ✅ Environments where CLI is unavailable
**When to prefer CLI + hooks:**
- ✅ Claude Code, Cursor, Windsurf, or any environment with shell access
- ✅ When context efficiency matters (most cases)
- ✅ Multi-editor workflows (CLI is universal)
See `integrations/beads-mcp/README.md` for MCP documentation. For multi-repo MCP patterns, see [docs/MULTI_REPO_AGENTS.md](docs/MULTI_REPO_AGENTS.md).
### Import Configuration ### Import Configuration
bd provides configuration for handling edge cases during import, especially when dealing with hierarchical issues and deleted parents: bd provides configuration for handling edge cases during import, especially when dealing with hierarchical issues and deleted parents:
@@ -691,26 +648,15 @@ bd automatically syncs with git:
- Imports from JSONL when newer (e.g., after `git pull`) - Imports from JSONL when newer (e.g., after `git pull`)
- No manual export/import needed! - No manual export/import needed!
### MCP Server (Recommended) ### MCP Server (Alternative)
If using Claude or MCP-compatible clients, install the beads MCP server: For MCP-only environments (Claude Desktop, no shell access), install the MCP server:
```bash ```bash
pip install beads-mcp pip install beads-mcp
``` ```
Add to MCP config (e.g., `~/.config/claude/config.json`): **Prefer CLI + hooks** when shell access is available - it uses less context and is more efficient.
```json
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
```
Then use `mcp__beads__*` functions instead of CLI commands.
### Managing AI-Generated Planning Documents ### Managing AI-Generated Planning Documents

33
docs/CLAUDE_INTEGRATION.md
View File

@@ -4,11 +4,38 @@ This document explains design decisions for Claude Code integration in beads.
## Integration Approach ## Integration Approach
Beads uses a simple, universal approach to Claude Code integration: **Recommended: CLI + Hooks** - Beads uses a simple, universal approach to Claude Code integration:
- `bd prime` command for context injection - `bd prime` command for context injection (~1-2k tokens)
- Hooks (SessionStart/PreCompact) for automatic context refresh - Hooks (SessionStart/PreCompact) for automatic context refresh
- Direct CLI commands with `--json` flags
- Optional: Plugin for slash commands and enhanced UX - Optional: Plugin for slash commands and enhanced UX
- Optional: MCP server for native tool access (legacy)
**Alternative: MCP Server** - For MCP-only environments (Claude Desktop, no shell):
- Higher context overhead (MCP tool schemas)
- Use only when CLI is unavailable
## Why CLI + Hooks Over MCP?
**Context efficiency matters**, even with large context windows:
1. **Compute cost scales with tokens** - Every token in your context consumes compute on every inference, regardless of whether it's used
2. **Latency increases with context** - Larger prompts take longer to process
3. **Energy consumption** - Each token has environmental impact; lean prompts are more sustainable
4. **Attention quality** - Models attend better to smaller, focused contexts
**The math:**
- MCP tool schemas can add 10-50k tokens to context (depending on number of tools)
- `bd prime` adds ~1-2k tokens of workflow context
- That's 10-50x less context overhead
**When context size doesn't matter:**
- MCP-only environments where CLI isn't available (Claude Desktop)
- Very short conversations where context overhead is negligible
**When to prefer CLI + hooks:**
- Any environment with shell access (Claude Code, Cursor, Windsurf, etc.)
- Long conversations or coding sessions
- Multi-editor workflows (CLI is universal)
## Why Not Claude Skills? ## Why Not Claude Skills?

57
docs/INSTALLING.md
View File

@@ -121,26 +121,37 @@ bd version
## IDE and Editor Integrations ## IDE and Editor Integrations
### Claude Code Plugin ### CLI + Hooks (Recommended for Claude Code)
For Claude Code users, the beads plugin provides slash commands and MCP tools. **The recommended approach** for Claude Code, Cursor, Windsurf, and other editors with shell access:
**Prerequisites:** ```bash
1. First, install the bd CLI (see above) # 1. Install bd CLI (see Quick Install above)
2. Install `uv` (Python package manager) - required for the MCP server: brew install bd
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or via Homebrew # 2. Initialize in your project
brew install uv cd your-project
bd init --quiet
# Or via pip # 3. Install hooks for automatic context injection
pip install uv bd hooks install
``` ```
After installation, restart your shell or run `source ~/.local/bin/env` to update PATH.
3. Then install the plugin: **How it works:**
- SessionStart hook runs `bd prime` automatically
- `bd prime` injects ~1-2k tokens of workflow context
- You use `bd` CLI commands directly
- Git hooks auto-sync the database
**Why this is recommended:**
- **Context efficient** - ~1-2k tokens vs 10-50k for MCP tool schemas
- **Lower latency** - Direct CLI calls, no MCP protocol overhead
- **Universal** - Works with any editor that has shell access
- **More sustainable** - Less compute per request
### Claude Code Plugin (Optional)
For enhanced UX with slash commands:
```bash ```bash
# In Claude Code # In Claude Code
@@ -149,16 +160,15 @@ For Claude Code users, the beads plugin provides slash commands and MCP tools.
# Restart Claude Code # Restart Claude Code
``` ```
The plugin includes: The plugin adds:
- Slash commands: `/bd-ready`, `/bd-create`, `/bd-show`, `/bd-update`, `/bd-close`, etc. - Slash commands: `/bd-ready`, `/bd-create`, `/bd-show`, `/bd-update`, `/bd-close`, etc.
- Full MCP server with all bd tools
- Task agent for autonomous execution - Task agent for autonomous execution
See [PLUGIN.md](PLUGIN.md) for complete plugin documentation. See [PLUGIN.md](PLUGIN.md) for complete plugin documentation.
### MCP Server (For Sourcegraph Amp, Claude Desktop, and other MCP clients) ### MCP Server (Alternative - for MCP-only environments)
If you're using an MCP-compatible tool other than Claude Code: **Use MCP only when CLI is unavailable** (Claude Desktop, Sourcegraph Amp without shell):
```bash ```bash
# Using uv (recommended) # Using uv (recommended)
@@ -195,11 +205,10 @@ Add to your MCP settings:
} }
``` ```
**What you get:** **Trade-offs:**
- Full bd functionality exposed via MCP protocol - ✅ Works in MCP-only environments
- Tools for creating, updating, listing, and closing issues - ❌ Higher context overhead (MCP schemas add 10-50k tokens)
- Ready work detection and dependency management - ❌ Additional latency from MCP protocol
- All without requiring Bash commands
See [integrations/beads-mcp/README.md](integrations/beads-mcp/README.md) for detailed MCP server documentation. See [integrations/beads-mcp/README.md](integrations/beads-mcp/README.md) for detailed MCP server documentation.

2
examples/claude-desktop-mcp/README.md
View File

@@ -2,6 +2,8 @@
> **Note**: The beads MCP server is now fully implemented! See [integrations/beads-mcp](../../integrations/beads-mcp/) for the production implementation. > **Note**: The beads MCP server is now fully implemented! See [integrations/beads-mcp](../../integrations/beads-mcp/) for the production implementation.
> **Recommendation**: For environments with shell access (Claude Code, Cursor, Windsurf), use **CLI + hooks** instead of MCP. It uses ~1-2k tokens vs 10-50k for MCP schemas, resulting in lower compute cost and latency. **Use MCP only for MCP-only environments** like Claude Desktop where CLI is unavailable.
## What This Provides ## What This Provides
An MCP server that exposes bd functionality to Claude Desktop and other MCP clients, allowing Claude to: An MCP server that exposes bd functionality to Claude Desktop and other MCP clients, allowing Claude to:

4
integrations/beads-mcp/README.md
View File

@@ -3,6 +3,10 @@
MCP server for [beads](https://github.com/steveyegge/beads) issue tracker and agentic memory system. MCP server for [beads](https://github.com/steveyegge/beads) issue tracker and agentic memory system.
Enables AI agents to manage tasks using bd CLI through Model Context Protocol. Enables AI agents to manage tasks using bd CLI through Model Context Protocol.
> **Note:** For environments with shell access (Claude Code, Cursor, Windsurf), the **CLI + hooks approach is recommended** over MCP. It uses ~1-2k tokens vs 10-50k for MCP schemas, resulting in lower compute cost and latency. See the [main README](../../README.md) for CLI setup.
>
> **Use this MCP server** for MCP-only environments like Claude Desktop where CLI access is unavailable.
## Installing ## Installing
Install from PyPI: Install from PyPI: