beads/website/docs/integrations/github-copilot.md
Amp a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
Systematic cleanup of stale documentation references left over from the
Dolt migration:

- Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files
- Replace all 'bd import' → 'bd init --from-jsonl' or remove
- Replace 'bd init --branch' → note about refs/dolt/data separation
- Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly)
- Fix npm-package, claude-plugin, integrations, examples, website docs

Add scripts/check-doc-flags.sh to catch stale doc references:
- Checks for removed commands (bd sync, bd import)
- Checks for removed flags (bd init --branch)
- Warns on legacy SQLite/beads.db references
- Compares CLI_REFERENCE.md against bd help --all

Add CI job (check-doc-flags) and Makefile target (check-docs) to gate
PRs against doc freshness.

Prior art: feat/help-doc-generator branch has bd help --doc/--list for
generating docs FROM CLI output. This script validates docs AGAINST CLI
output — complementary approaches.

Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 13:25:40 -07:00

2.9 KiB

id title sidebar_position
github-copilot GitHub Copilot 4

GitHub Copilot Integration

How to use beads with GitHub Copilot in VS Code.

Setup

Quick Setup

  1. Install beads-mcp:

    uv tool install beads-mcp
    
  2. 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": []
        }
      }
    }
    
  3. Initialize beads:

    bd init --quiet
    
  4. Reload VS Code

Verify Setup

Ask Copilot Chat: "What beads issues are ready to work on?"

Using Natural Language

With MCP configured, interact naturally:

You: Create a bug for the login timeout
Copilot: Created bd-42: Login timeout bug

You: What issues are ready?
Copilot: 3 issues ready: bd-42, bd-99, bd-17

You: Close bd-42, it's fixed
Copilot: Closed bd-42

MCP Tools

Tool Description
beads_ready List unblocked issues
beads_create Create new issue
beads_show Show issue details
beads_update Update issue
beads_close Close issue
beads_dolt_push Push to Dolt remote
beads_dep_add Add dependency
beads_dep_tree Show dependency tree

Copilot Instructions

Optionally add .github/copilot-instructions.md:

## Issue Tracking

This project uses **bd (beads)** for issue tracking.
Run `bd prime` for workflow context.

Quick reference:
- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd dolt push` - Push changes to Dolt remote

Troubleshooting

Tools not appearing

  1. Check VS Code 1.96+
  2. Verify mcp.json syntax is valid JSON
  3. Reload VS Code window
  4. Check Output panel for MCP errors

"beads-mcp not found"

# Check installation
which beads-mcp

# Reinstall if needed
uv tool install beads-mcp --force

No database found

bd init --quiet

FAQ

Do I need to clone beads?

No. Beads is a system-wide CLI tool. Install once, use everywhere. The .beads/ directory in your project only contains the issue database.

What about git hooks?

Git hooks are optional. They auto-sync issues but you can skip them during bd init and manually run bd dolt push / bd dolt pull instead.

See Also