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

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?
 

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.