From 80e56d58f3ada4a229e31359ae2eb5cfeb040f03 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sun, 14 Dec 2025 17:20:10 -0800 Subject: [PATCH] docs: document bd setup command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive documentation for the `bd setup` command: - New docs/SETUP.md with full documentation for all three integrations: - Claude Code (hooks for SessionStart/PreCompact) - Cursor IDE (rules file in .cursor/rules/) - Aider (config file with human-in-the-loop workflow) - Updated docs/CLI_REFERENCE.md: - Added Setup & Integration section - Added SETUP.md to See Also links - Added to Quick Navigation Closes #518 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/CLI_REFERENCE.md | 20 ++++ docs/SETUP.md | 241 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 261 insertions(+) create mode 100644 docs/SETUP.md diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index fb01f911..8afe7d2d 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -11,6 +11,7 @@ - [Filtering & Search](#filtering--search) - [Advanced Operations](#advanced-operations) - [Database Management](#database-management) +- [Setup & Integration](#setup--integration) ## Basic Operations @@ -550,10 +551,29 @@ bd sync # Force immediate sync, bypass debounce **ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately. +## Setup & Integration + +Configure beads integration with AI coding tools: + +```bash +# Setup integration +bd setup claude # Claude Code hooks (SessionStart/PreCompact) +bd setup cursor # Cursor IDE rules file +bd setup aider # Aider configuration + +# Check/remove integration +bd setup claude --check # Verify installation +bd setup claude --remove # Remove hooks +bd setup claude --project # Project-only (not global) +``` + +See [SETUP.md](SETUP.md) for detailed documentation on each integration. + ## See Also - [AGENTS.md](../AGENTS.md) - Main agent workflow guide - [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode - [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies - [LABELS.md](../LABELS.md) - Label system guide +- [SETUP.md](SETUP.md) - AI tool integration setup - [README.md](../README.md) - User documentation diff --git a/docs/SETUP.md b/docs/SETUP.md new file mode 100644 index 00000000..320851e9 --- /dev/null +++ b/docs/SETUP.md @@ -0,0 +1,241 @@ +# Setup Command Reference + +**For:** Setting up beads integration with AI coding tools +**Version:** 0.29.0+ + +## Overview + +The `bd setup` command configures beads integration with AI coding tools. It supports three integrations: + +| Tool | Command | Integration Type | +|------|---------|-----------------| +| [Claude Code](#claude-code) | `bd setup claude` | SessionStart/PreCompact hooks | +| [Cursor IDE](#cursor-ide) | `bd setup cursor` | Rules file (.cursor/rules/beads.mdc) | +| [Aider](#aider) | `bd setup aider` | Config file (.aider.conf.yml) | + +## Quick Start + +```bash +# Install integration for your tool +bd setup claude # For Claude Code +bd setup cursor # For Cursor IDE +bd setup aider # For Aider + +# Verify installation +bd setup claude --check +bd setup cursor --check +bd setup aider --check +``` + +## Claude Code + +Claude Code integration uses hooks to automatically inject beads workflow context at session start and before context compaction. + +### Installation + +```bash +# Global installation (recommended) +bd setup claude + +# Project-only installation +bd setup claude --project + +# With stealth mode (flush only, no git operations) +bd setup claude --stealth +``` + +### What Gets Installed + +**Global installation** (`~/.claude/settings.json`): +- `SessionStart` hook: Runs `bd prime` when a new session starts +- `PreCompact` hook: Runs `bd prime` before context compaction + +**Project installation** (`.claude/settings.local.json`): +- Same hooks, but only active for this project + +### Flags + +| Flag | Description | +|------|-------------| +| `--check` | Check if integration is installed | +| `--remove` | Remove beads hooks | +| `--project` | Install for this project only (not globally) | +| `--stealth` | Use `bd prime --stealth` (flush only, no git operations) | + +### Examples + +```bash +# Check if hooks are installed +bd setup claude --check +# Output: ✓ Global hooks installed: /Users/you/.claude/settings.json + +# Remove hooks +bd setup claude --remove + +# Install project-specific hooks with stealth mode +bd setup claude --project --stealth +``` + +### How It Works + +The hooks call `bd prime` which: +1. Outputs workflow context for Claude to read +2. Syncs any pending changes +3. Ensures Claude always knows how to use beads + +This is more context-efficient than MCP tools (~1-2k tokens vs 10-50k for MCP schemas). + +## Cursor IDE + +Cursor integration creates a rules file that provides beads workflow context to the AI. + +### Installation + +```bash +bd setup cursor +``` + +### What Gets Installed + +Creates `.cursor/rules/beads.mdc` with: +- Core workflow rules (track work in bd, not markdown TODOs) +- Quick command reference +- Workflow pattern (ready → claim → work → close → sync) +- Context loading instructions + +### Flags + +| Flag | Description | +|------|-------------| +| `--check` | Check if integration is installed | +| `--remove` | Remove beads rules file | + +### Examples + +```bash +# Check if rules are installed +bd setup cursor --check +# Output: ✓ Cursor integration installed: .cursor/rules/beads.mdc + +# Remove rules +bd setup cursor --remove +``` + +### How It Works + +Cursor reads `.cursor/rules/*.mdc` files and includes them in the AI's context. The beads rules file teaches the AI: +- To use `bd ready` for finding work +- To use `bd create` for tracking new issues +- To use `bd sync` at session end +- The basic workflow pattern + +## Aider + +Aider integration creates configuration files that teach the AI about beads, while respecting Aider's human-in-the-loop design. + +### Installation + +```bash +bd setup aider +``` + +### What Gets Installed + +| File | Purpose | +|------|---------| +| `.aider.conf.yml` | Points Aider to read the instructions file | +| `.aider/BEADS.md` | Workflow instructions for the AI | +| `.aider/README.md` | Quick reference for humans | + +### Flags + +| Flag | Description | +|------|-------------| +| `--check` | Check if integration is installed | +| `--remove` | Remove beads configuration | + +### Examples + +```bash +# Check if config is installed +bd setup aider --check +# Output: ✓ Aider integration installed: .aider.conf.yml + +# Remove configuration +bd setup aider --remove +``` + +### How It Works + +Unlike Claude Code, Aider requires explicit command execution. The AI will **suggest** bd commands, which the user runs via `/run`: + +``` +You: What issues are ready to work on? + +Aider: Let me check. Run: +/run bd ready + +You: [runs the command] + +Aider: Great! To claim bd-42, run: +/run bd update bd-42 --status in_progress +``` + +This respects Aider's philosophy of keeping humans in control while still leveraging beads for issue tracking. + +## Comparison + +| Feature | Claude Code | Cursor | Aider | +|---------|-------------|--------|-------| +| Command execution | Automatic | Automatic | Manual (/run) | +| Context injection | Hooks | Rules file | Config file | +| Global install | Yes | No (per-project) | No (per-project) | +| Stealth mode | Yes | N/A | N/A | + +## Best Practices + +1. **Install globally for Claude Code** - You'll get beads context in every project automatically + +2. **Install per-project for Cursor/Aider** - These tools expect project-local configuration + +3. **Use stealth mode in CI/CD** - `bd setup claude --stealth` avoids git operations that might fail in automated environments + +4. **Run `bd doctor` after setup** - Verifies the integration is working: + ```bash + bd doctor | grep -i claude + # Claude Integration: Hooks installed (CLI mode) + ``` + +## Troubleshooting + +### "Hooks not working" + +1. Restart your AI tool after installation +2. Verify with `bd setup --check` +3. Check `bd doctor` output for integration status + +### "Context not appearing" + +For Claude Code, ensure `bd prime` works standalone: +```bash +bd prime +``` + +If this fails, fix the underlying beads issue first. + +### "Want to switch from global to project hooks" + +```bash +# Remove global hooks +bd setup claude --remove + +# Install project hooks +bd setup claude --project +``` + +## Related Documentation + +- [CLAUDE_INTEGRATION.md](CLAUDE_INTEGRATION.md) - Design decisions for Claude Code integration +- [AIDER_INTEGRATION.md](AIDER_INTEGRATION.md) - Detailed Aider workflow guide +- [QUICKSTART.md](QUICKSTART.md) - Getting started with beads +- [CLI_REFERENCE.md](CLI_REFERENCE.md) - Full command reference