beads/website/docs/getting-started/ide-setup.md
Scott Nixon 18f47fe8b6
docs: add GitHub Copilot integration guide with cross-platform MCP paths (#1348)
* fix(export): populate export_hashes after successful export (GH#1278)

Child issues created with --parent were missing from export_hashes table,
which affects integrity tracking and future incremental export features.

This fix ensures SetExportHash() is called for all exported issues:
- Updated ExportResult to include IssueContentHashes map
- Updated finalizeExport() to call SetExportHash() for each exported issue
- Updated exportToJSONLDeferred() to collect content hashes during export
- Updated performIncrementalExport() to collect content hashes for dirty issues
- Updated exportToJSONLWithStore() to call SetExportHash() after export
- Updated daemon's handleExport() to call SetExportHash() after export

Added test TestExportPopulatesExportHashes to verify the fix works for
both regular and hierarchical (child) issue IDs.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add GitHub Copilot integration guide

Add comprehensive documentation for using beads with GitHub Copilot in VS Code via the MCP server.

New files:
- docs/COPILOT_INTEGRATION.md - Complete setup guide with prerequisites, MCP tools reference, example workflows, troubleshooting, and FAQ
- website/docs/integrations/github-copilot.md - Shorter website version

Updated files:
- docs/INSTALLING.md - Added GitHub Copilot row to setup matrix and new "GitHub Copilot (VS Code)" section with quick setup steps
- website/docs/getting-started/ide-setup.md - Added GitHub Copilot section
- website/docs/integrations/mcp-server.md - Added VS Code / GitHub Copilot configuration examples for both .vscode/mcp.json and settings.json

Key clarifications:
- Beads is a system-wide CLI tool installed once, not cloned into projects
- The .beads/ directory only contains the issue database
- Added FAQ addressing "Do I need to clone beads?" explicitly

Fixes #148

* docs: add cross-platform paths for user-level VS Code MCP config

  Add Linux and Windows paths alongside macOS for the VS Code
  user-level MCP configuration. Users can now find the correct
  path for their platform in a simple table format.

  Paths by platform:
  - macOS: ~/Library/Application Support/Code/User/mcp.json
  - Linux: ~/.config/Code/User/mcp.json
  - Windows: %APPDATA%\Code\User\mcp.json

  Fixes #148

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 11:25:14 -08:00

3.4 KiB

id title sidebar_position
ide-setup IDE Setup 3

IDE Setup for AI Agents

Configure your IDE for optimal beads integration.

Claude Code

The recommended approach for Claude Code:

# Setup Claude Code integration
bd setup claude

This installs:

  • SessionStart hook - Runs bd prime when Claude Code starts
  • PreCompact hook - Ensures bd sync before context compaction

How it works:

  1. SessionStart hook runs bd prime automatically
  2. bd prime injects ~1-2k tokens of workflow context
  3. You use bd CLI commands directly
  4. Git hooks auto-sync the database

Verify installation:

bd setup claude --check

Manual Setup

If you prefer manual configuration, add to your Claude Code hooks:

{
  "hooks": {
    "SessionStart": ["bd prime"],
    "PreCompact": ["bd sync"]
  }
}

Cursor IDE

# Setup Cursor integration
bd setup cursor

This creates .cursor/rules/beads.mdc with beads-aware rules.

Verify:

bd setup cursor --check

Aider

# Setup Aider integration
bd setup aider

This creates/updates .aider.conf.yml with beads context.

Verify:

bd setup aider --check

GitHub Copilot

For VS Code with GitHub Copilot, use the MCP server:

# Install MCP server
uv tool install beads-mcp

Create .vscode/mcp.json in your project:

{
  "servers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

For all projects: Add to VS Code user-level MCP config:

Platform Path
macOS ~/Library/Application Support/Code/User/mcp.json
Linux ~/.config/Code/User/mcp.json
Windows %APPDATA%\Code\User\mcp.json
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}

Initialize beads and reload VS Code:

bd init --quiet

See GitHub Copilot Integration for detailed setup.

Context Injection with bd prime

All integrations use bd prime to inject context:

bd prime

This outputs a compact (~1-2k tokens) workflow reference including:

  • Available commands
  • Current project status
  • Workflow patterns
  • Best practices

Why context efficiency matters:

  • Compute cost scales with tokens
  • Latency increases with context size
  • Models attend better to smaller, focused contexts

MCP Server (Alternative)

For MCP-only environments (Claude Desktop, no shell access):

# Install MCP server
pip install beads-mcp

Add to Claude Desktop config:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

Trade-offs:

  • Works in MCP-only environments
  • Higher context overhead (10-50k tokens for tool schemas)
  • Additional latency from MCP protocol

See MCP Server for detailed configuration.

Git Hooks

Ensure git hooks are installed for auto-sync:

bd hooks install

This installs:

  • pre-commit - Validates changes before commit
  • post-merge - Imports changes after pull
  • pre-push - Ensures sync before push

Check hook status:

bd info  # Shows warnings if hooks are outdated

Verifying Your Setup

Run a complete health check:

# Check version
bd version

# Check daemon
bd info

# Check hooks
bd hooks status

# Check editor integration
bd setup claude --check   # or cursor, aider