Skip to main content
Version: Next

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:

    PlatformPath
    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​

ToolDescription
beads_readyList unblocked issues
beads_createCreate new issue
beads_showShow issue details
beads_updateUpdate issue
beads_closeClose issue
beads_dolt_pushPush to Dolt remote
beads_dep_addAdd dependency
beads_dep_treeShow 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 refresh exports and legacy fallback checks, while issue sync uses bd dolt push / bd dolt pull.

See Also​