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-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"}

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.
### 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

33
docs/CLAUDE_INTEGRATION.md
View File

@@ -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?

57
docs/INSTALLING.md
View File

@@ -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.

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.
> **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:

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.
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: