From 0f008d3979cb625a293f7081504704a4c9d0f936 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sun, 28 Dec 2025 14:00:05 -0800 Subject: [PATCH] docs: Add components overview explaining CLI vs Plugin vs MCP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarifies the relationship between bd CLI, Claude Code Plugin, and MCP server. Most users only need the CLI. Closes #782 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/INSTALLING.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md index 8d341b8b..f9700eda 100644 --- a/docs/INSTALLING.md +++ b/docs/INSTALLING.md @@ -2,6 +2,32 @@ Complete installation guide for all platforms. +## Components Overview + +Beads has several components - here's what they are and when you need them: + +| Component | What It Is | When You Need It | +|-----------|------------|------------------| +| **bd CLI** | Core command-line tool | Always - this is the foundation | +| **Claude Code Plugin** | Slash commands + enhanced UX | Optional - if you want `/bd-ready`, `/bd-create` commands | +| **MCP Server (beads-mcp)** | Model Context Protocol interface | Only for MCP-only environments (Claude Desktop, Amp) | + +**How they relate:** +- The **bd CLI** is the core - install it first via Homebrew, npm, or script +- The **Plugin** enhances Claude Code with slash commands but *requires* the CLI installed +- The **MCP server** is an *alternative* to the CLI for environments without shell access + +**Typical setups:** + +| Environment | What to Install | +|-------------|-----------------| +| Claude Code, Cursor, Windsurf | bd CLI (+ optional Plugin for Claude Code) | +| Claude Desktop (no shell) | MCP server only | +| Terminal / scripts | bd CLI only | +| CI/CD pipelines | bd CLI only | + +**Are they mutually exclusive?** No - you can have CLI + Plugin + MCP all installed. They don't conflict. But most users only need the CLI. + ## Quick Install (Recommended) ### Homebrew (macOS/Linux)