- mint.sh + make docs-dev: local preview of the docs/ Mintlify site (Node 22 handling modeled on the Gas City wrapper). - test/docsync: Go guard keeping docs/ and docs.json in exact correspondence — every nav entry has a file, every page is in the nav (tiny stub allowlist for paths released bd binaries print), published pages use root-relative extensionless links that resolve, and engdocs/ plus curated root markdown keep exact GitHub-style paths. Wired into make check-docs. - .github/workflows/docs-mintlify.yml: docsync + baseline-aware mint broken-links check on PRs touching docs/**. - Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six mirrored files now live once in the Mintlify site; the committed Docusaurus mirrors stay frozen so the parallel-run site keeps building. - Repoint inbound links to moved docs across README, guides, examples, npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md pointer stub (bd's agent templates print that path). Runtime strings in cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print old paths — covered by stubs, flagged in the PR.
3.5 KiB
3.5 KiB
| title |
|---|
| GitHub Copilot CLI Integration Design |
This document explains design decisions for GitHub Copilot CLI integration in beads.
For VS Code + MCP, see COPILOT_INTEGRATION.md.
Integration Approach
Recommended: Copilot CLI plugin + repository instructions - Beads uses Copilot CLI's native plugin manifest plus repository instructions:
.copilot-plugin/plugin.jsonregistersbd primehooks natively.github/copilot-instructions.mdprovides repository-specific workflow guidance- Direct CLI commands with
--jsonflags remain the primary operational interface
Alternative: VS Code MCP - For Copilot Chat in the editor:
- Native tool calling through MCP
- Higher context overhead from tool schemas
- Use when you want editor-native tool access instead of terminal-first workflow
Why Plugin + Instructions Over Custom Setup Code?
The plugin manifest already models the behavior we want:
-
Hooks belong in the tool's native format
- Copilot CLI understands plugin manifests directly
SessionStartandPreCompactcan be declared as data instead of custom Go logic- This keeps beads core smaller and easier to maintain
-
Instructions stay explicit and reviewable
- Repository guidance still lives in
.github/copilot-instructions.md - Teams can review the instructions like any other project documentation
- The hook behavior and the human-readable guidance stay separate
- Repository guidance still lives in
-
Lower maintenance burden
- No Copilot-specific install/check/remove implementation in core
- No Copilot-specific doctor checks
- The recipe just writes the native plugin file and the instruction file
Why Copilot CLI Over MCP for Terminal Work?
Context efficiency still matters, even with large context windows:
- Compute cost scales with tokens - Every token in context is processed on every inference
- Latency increases with context - Smaller prompts keep the CLI more responsive
- Energy consumption - Lean prompts are more sustainable over long sessions
- Attention quality - Models generally perform better with tighter, more relevant context
The math:
- MCP tool schemas can add 10-50k tokens to context
bd primeadds ~1-2k tokens of workflow context- That is an order-of-magnitude reduction in overhead
Installation
# Install the Copilot CLI plugin manifest + repository instructions
bd setup copilot
# Check installation status
bd setup copilot --check
# Remove the integration
bd setup copilot --remove
What it installs:
.copilot-plugin/plugin.jsonSessionStarthook: Runsbd primewhen Copilot CLI starts a sessionPreCompacthook: Runsbd primebefore context compaction
.github/copilot-instructions.md- Repository workflow guidance for Copilot CLI
Related Files
plugins/beads/.copilot-plugin/plugin.json- Source plugin manifest for the shared plugin packageplugins/beads/copilot_manifest.go- Embedded manifest source used bybd setup copilotinternal/recipes/recipes.go- Lightweightcopilotrecipe definitioninternal/recipes/template.go- Static Copilot instructions template used bybd setup- GitHub Copilot integration - VS Code MCP integration