gastownhall__beads/docs/integrations/copilot-cli.md

title, description

title	description
GitHub Copilot CLI Integration Design	Design rationale and setup for the Copilot CLI integration, which uses a plugin manifest plus repository instructions

This document explains design decisions for GitHub Copilot CLI integration in beads.

For VS Code + MCP, see GitHub Copilot.

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

Related Files

• 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

• GitHub Copilot CLI docs
• Adding repository custom instructions for GitHub Copilot CLI