* fix(init): wire git origin as Dolt remote Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync. Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only. _codex-gpt-5-xhigh on behalf of maphew_ * test: keep embedded command stderr out of parsed stdout Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_ --------- Co-authored-by: CI Bot <ci@beads.test>
145 lines
2.9 KiB
Markdown
145 lines
2.9 KiB
Markdown
---
|
|
id: github-copilot
|
|
title: GitHub Copilot
|
|
sidebar_position: 4
|
|
---
|
|
|
|
# GitHub Copilot Integration
|
|
|
|
How to use beads with GitHub Copilot in VS Code.
|
|
|
|
## Setup
|
|
|
|
### Quick Setup
|
|
|
|
1. Install beads-mcp:
|
|
```bash
|
|
uv tool install beads-mcp
|
|
```
|
|
|
|
2. Create `.vscode/mcp.json` in your project:
|
|
```json
|
|
{
|
|
"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` |
|
|
|
|
```json
|
|
{
|
|
"servers": {
|
|
"beads": {
|
|
"command": "beads-mcp",
|
|
"args": []
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
3. Initialize beads:
|
|
```bash
|
|
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`:
|
|
|
|
```markdown
|
|
## 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"
|
|
|
|
```bash
|
|
# Check installation
|
|
which beads-mcp
|
|
|
|
# Reinstall if needed
|
|
uv tool install beads-mcp --force
|
|
```
|
|
|
|
### No database found
|
|
|
|
```bash
|
|
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](/integrations/mcp-server) - Detailed MCP configuration
|
|
- [Installation](/getting-started/installation) - Full install guide
|
|
- [Detailed Copilot Guide](https://github.com/gastownhall/beads/blob/main/docs/COPILOT_INTEGRATION.md) - Comprehensive documentation
|