beads/docs/integrations/github-copilot.md
Chris Sells 5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
2026-07-12 10:37:07 -07:00

6.1 KiB

title
GitHub Copilot

Beads gives Copilot a persistent, structured memory for tracking work: with the MCP server configured, you create, update, and track issues in natural language without leaving the editor.

This page covers Copilot Chat in VS Code via MCP. For the terminal-based Copilot CLI plugin installed by bd setup copilot, see Copilot CLI.

Prerequisites

  • VS Code 1.96+ with the GitHub Copilot extension
  • A GitHub Copilot subscription (Individual, Business, or Enterprise)
  • The beads CLI installed (installation guide)
  • Python 3.10+ or the uv package manager

Setup

Quick Setup

  1. Install beads-mcp:

    # Using uv (recommended)
    uv tool install beads-mcp
    
    # Or using pip / pipx
    pip install beads-mcp
    pipx 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
    

    This creates a .beads/ directory with the issue database.

  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: Claim bd-42, I'll take it
Copilot: Claimed bd-42 and started work

You: I found a related bug - the session token isn't refreshed.
     File it, linked to bd-42.
Copilot: Created bd-103: Session token not refreshed
         Linked as discovered-from bd-42

You: Close bd-42 with reason "Fixed timeout handling"
Copilot: Closed bd-42: Fixed timeout handling

Syncing stays on the CLI: run bd dolt push at the end of a session. There is no MCP push tool.

MCP Tools

Tool Description You say
ready List unblocked issues "What can I work on?"
list List issues with filters "Show all open bugs"
show Show issue details, including dependencies and dependents "Show bd-42 details"
create Create new issue "Create a task for refactoring"
claim Atomically claim an issue (assignee + in_progress) "I'll take bd-42"
update Update issue fields "Set bd-42 to priority 1"
close Close an issue "Complete bd-42"
dep Add dependency "bd-99 blocks bd-42"
blocked Show blocked issues and their blockers "What's blocking my work?"
stats Issue counts and average lead time "How's the backlog?"

The server also exposes reopen, comment, comments, note, context, and admin; call discover_tools for the full catalog.

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 (run at session end)

CLI vs MCP

Approach Best for Trade-off
MCP (Copilot Chat) Natural language, discovery Higher token overhead
CLI (terminal) Scripting, precision, speed Requires shell access

Both work against the same database - use MCP for conversational work, the CLI for quick commands. See MCP Server for the full trade-off discussion.

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
beads-mcp --version

# uv installs to ~/.local/bin - make sure it's on PATH
export PATH="$HOME/.local/bin:$PATH"

# If installed with pip, find it
pip show beads-mcp | grep Location

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

No database found

bd init --quiet

Changes not persisting

Push to the Dolt remote at the end of your session, from the terminal:

bd dolt push

Organization policies blocking MCP

For Copilot Business/Enterprise, your organization must enable the "MCP servers in Copilot" policy. Contact your admin if MCP tools don't appear despite a correct config.

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. They never modify your source code; skip them with bd init --skip-hooks.

Can I use beads without Copilot?

Yes. The same database works from the terminal, Claude Code, Cursor, Aider, and any editor with MCP or shell access.

Does this work with Copilot in other editors?

This page covers VS Code. For JetBrains IDEs, check whether your IDE supports MCP; the config location differs. For Neovim, use the CLI directly. For the terminal, see Copilot CLI.

See Also