diff --git a/.beads/beads.jsonl b/.beads/beads.jsonl index 60ce0f3ea..a4f5d4659 100644 --- a/.beads/beads.jsonl +++ b/.beads/beads.jsonl @@ -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-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-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-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"} diff --git a/AGENTS.md b/AGENTS.md index 7a9b0bf14..d0d1c1ce8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. -### 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:** - -```bash -# Install the MCP server -pip install beads-mcp - -# 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). +- **Minimizes context usage** - Only injects ~1-2k tokens via `bd prime` vs MCP tool schemas +- **Reduces compute cost** - Less tokens = less processing per request +- **Lower latency** - Direct CLI calls are faster than MCP protocol overhead +- **More sustainable** - Every token has compute/energy cost; lean prompts are greener +- **Universal** - Works with any AI assistant, not just MCP-compatible ones **Setup (one-time):** ```bash -# MCP config in ~/.config/amp/settings.json or Claude Desktop config: -{ - "beads": { - "command": "beads-mcp", - "args": [] - } -} +# Install bd CLI (see docs/INSTALLING.md) +brew install bd # or other methods + +# Initialize in your project +bd init --quiet + +# Install hooks for automatic context injection +bd hooks install ``` -**How it works (LSP model):** -The single MCP server instance automatically: +**How it works:** -1. Checks for local daemon socket (`.beads/bd.sock`) in your current workspace -2. Routes requests to the correct **per-project daemon** based on working directory -3. Auto-starts the local daemon if not running (with exponential backoff) -4. **Each project gets its own isolated daemon** serving only its database +1. **SessionStart hook** runs `bd prime` automatically when Claude Code starts +2. `bd prime` injects a compact workflow reference (~1-2k tokens) +3. You use `bd` CLI commands directly (no MCP layer needed) +4. Git hooks auto-sync the database with JSONL -**Architecture:** +**Why context minimization matters:** -``` -MCP Server (one instance) - ↓ -Per-Project Daemons (one per workspace) - ↓ -SQLite Databases (complete isolation) -``` +Even with 200k+ context windows, minimizing context is important: +- **Compute cost scales with tokens** - More context = more expensive inference +- **Latency increases with context** - Larger prompts take longer to process +- **Energy consumption** - Every token has environmental impact +- **Attention quality** - Models attend better to smaller, focused contexts -**Why per-project daemons?** - -- ✅ 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. +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. ### 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). +### 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 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`) - 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 pip install beads-mcp ``` -Add to MCP config (e.g., `~/.config/claude/config.json`): - -```json -{ - "beads": { - "command": "beads-mcp", - "args": [] - } -} -``` - -Then use `mcp__beads__*` functions instead of CLI commands. +**Prefer CLI + hooks** when shell access is available - it uses less context and is more efficient. ### Managing AI-Generated Planning Documents diff --git a/docs/CLAUDE_INTEGRATION.md b/docs/CLAUDE_INTEGRATION.md index 2c94207c5..f0ce11fe0 100644 --- a/docs/CLAUDE_INTEGRATION.md +++ b/docs/CLAUDE_INTEGRATION.md @@ -4,11 +4,38 @@ This document explains design decisions for Claude Code integration in beads. ## Integration Approach -Beads uses a simple, universal approach to Claude Code integration: -- `bd prime` command for context injection +**Recommended: CLI + Hooks** - Beads uses a simple, universal approach to Claude Code integration: +- `bd prime` command for context injection (~1-2k tokens) - Hooks (SessionStart/PreCompact) for automatic context refresh +- Direct CLI commands with `--json` flags - 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? diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md index b1592a938..c3a90245d 100644 --- a/docs/INSTALLING.md +++ b/docs/INSTALLING.md @@ -121,26 +121,37 @@ bd version ## 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:** -1. First, install the bd CLI (see above) -2. Install `uv` (Python package manager) - required for the MCP server: - ```bash - # macOS/Linux - curl -LsSf https://astral.sh/uv/install.sh | sh +```bash +# 1. Install bd CLI (see Quick Install above) +brew install bd - # Or via Homebrew - brew install uv +# 2. Initialize in your project +cd your-project +bd init --quiet - # Or via pip - pip install uv - ``` - After installation, restart your shell or run `source ~/.local/bin/env` to update PATH. +# 3. Install hooks for automatic context injection +bd hooks install +``` -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 # In Claude Code @@ -149,16 +160,15 @@ For Claude Code users, the beads plugin provides slash commands and MCP tools. # Restart Claude Code ``` -The plugin includes: +The plugin adds: - 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 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 # Using uv (recommended) @@ -195,11 +205,10 @@ Add to your MCP settings: } ``` -**What you get:** -- Full bd functionality exposed via MCP protocol -- Tools for creating, updating, listing, and closing issues -- Ready work detection and dependency management -- All without requiring Bash commands +**Trade-offs:** +- ✅ Works in MCP-only environments +- ❌ Higher context overhead (MCP schemas add 10-50k tokens) +- ❌ Additional latency from MCP protocol See [integrations/beads-mcp/README.md](integrations/beads-mcp/README.md) for detailed MCP server documentation. diff --git a/examples/claude-desktop-mcp/README.md b/examples/claude-desktop-mcp/README.md index 104fa6cec..d451a2d2c 100644 --- a/examples/claude-desktop-mcp/README.md +++ b/examples/claude-desktop-mcp/README.md @@ -2,6 +2,8 @@ > **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 An MCP server that exposes bd functionality to Claude Desktop and other MCP clients, allowing Claude to: diff --git a/integrations/beads-mcp/README.md b/integrations/beads-mcp/README.md index fcdf8e0d9..3fde03829 100644 --- a/integrations/beads-mcp/README.md +++ b/integrations/beads-mcp/README.md @@ -3,6 +3,10 @@ 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. +> **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 Install from PyPI: