Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2.9 KiB
2.9 KiB
| title |
|---|
| GitHub Copilot |
How to use beads with GitHub Copilot in VS Code.
Setup
Quick Setup
-
Install beads-mcp:
uv tool install beads-mcp -
Create
.vscode/mcp.jsonin 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.jsonLinux ~/.config/Code/User/mcp.jsonWindows %APPDATA%\Code\User\mcp.json{ "servers": { "beads": { "command": "beads-mcp", "args": [] } } } -
Initialize beads:
bd init --quiet -
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
- Check VS Code 1.96+
- Verify mcp.json syntax is valid JSON
- Reload VS Code window
- 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
- MCP Server - Detailed MCP configuration
- Installation - Full install guide
- Detailed Copilot Guide - Comprehensive documentation