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).
This commit is contained in:
parent
7c4ac15a16
commit
5c2fe0d496
39 changed files with 2600 additions and 7116 deletions
|
|
@ -2,7 +2,16 @@
|
|||
title: GitHub Copilot
|
||||
---
|
||||
|
||||
How to use beads with GitHub Copilot in VS Code.
|
||||
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](/integrations/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](/getting-started/installation))
|
||||
- Python 3.10+ or the `uv` package manager
|
||||
|
||||
## Setup
|
||||
|
||||
|
|
@ -10,7 +19,12 @@ How to use beads with GitHub Copilot in VS Code.
|
|||
|
||||
1. Install beads-mcp:
|
||||
```bash
|
||||
# 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:
|
||||
|
|
@ -48,6 +62,8 @@ How to use beads with GitHub Copilot in VS Code.
|
|||
bd init --quiet
|
||||
```
|
||||
|
||||
This creates a `.beads/` directory with the issue database.
|
||||
|
||||
4. Reload VS Code
|
||||
|
||||
### Verify Setup
|
||||
|
|
@ -65,22 +81,36 @@ 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
|
||||
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 |
|
||||
|------|-------------|
|
||||
| `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 |
|
||||
| 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
|
||||
|
||||
|
|
@ -96,9 +126,18 @@ 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
|
||||
- `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](/integrations/mcp-server) for the full trade-off discussion.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tools not appearing
|
||||
|
|
@ -113,6 +152,13 @@ Quick reference:
|
|||
```bash
|
||||
# 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
|
||||
|
|
@ -124,6 +170,18 @@ uv tool install beads-mcp --force
|
|||
bd init --quiet
|
||||
```
|
||||
|
||||
### Changes not persisting
|
||||
|
||||
Push to the Dolt remote at the end of your session, from the terminal:
|
||||
|
||||
```bash
|
||||
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?
|
||||
|
|
@ -132,10 +190,20 @@ bd init --quiet
|
|||
|
||||
### 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`.
|
||||
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](/integrations/claude-code), [Cursor](/integrations/cursor), [Aider](/integrations/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](/integrations/copilot-cli).
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Server](/integrations/mcp-server) - Detailed MCP configuration
|
||||
- [Copilot CLI](/integrations/copilot-cli) - Terminal-based Copilot integration
|
||||
- [Quickstart](/getting-started/quickstart) - bd command basics
|
||||
- [Installation](/getting-started/installation) - Full install guide
|
||||
- [Detailed Copilot Guide](https://github.com/gastownhall/beads/blob/main/docs/COPILOT_INTEGRATION.md) - Comprehensive documentation
|
||||
- [Agent Instructions](https://github.com/gastownhall/beads/blob/main/AGENT_INSTRUCTIONS.md) - Full agent workflow reference
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue