beads/docs/integrations/copilot-cli.md
Chris Sells 3198395a32 docs(ci): add Mintlify preview, docsync guard, and broken-links workflow
- 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.
2026-07-12 10:37:07 -07:00

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.json registers bd prime hooks natively
  • .github/copilot-instructions.md provides repository-specific workflow guidance
  • Direct CLI commands with --json flags 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:

  1. Hooks belong in the tool's native format

    • Copilot CLI understands plugin manifests directly
    • SessionStart and PreCompact can be declared as data instead of custom Go logic
    • This keeps beads core smaller and easier to maintain
  2. 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
  3. 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:

  1. Compute cost scales with tokens - Every token in context is processed on every inference
  2. Latency increases with context - Smaller prompts keep the CLI more responsive
  3. Energy consumption - Lean prompts are more sustainable over long sessions
  4. Attention quality - Models generally perform better with tighter, more relevant context

The math:

  • MCP tool schemas can add 10-50k tokens to context
  • bd prime adds ~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.json
    • SessionStart hook: Runs bd prime when Copilot CLI starts a session
    • PreCompact hook: Runs bd prime before context compaction
  • .github/copilot-instructions.md
    • Repository workflow guidance for Copilot CLI
  • plugins/beads/.copilot-plugin/plugin.json - Source plugin manifest for the shared plugin package
  • plugins/beads/copilot_manifest.go - Embedded manifest source used by bd setup copilot
  • internal/recipes/recipes.go - Lightweight copilot recipe definition
  • internal/recipes/template.go - Static Copilot instructions template used by bd setup
  • GitHub Copilot integration - VS Code MCP integration

References