beads/docs/SETUP.md
Julian Palmerio 25703f8635
feat: add Copilot CLI setup recipe (#3839)
Adds `bd setup copilot` as a recipe-driven integration that installs a native Copilot CLI plugin manifest (.copilot-plugin/plugin.json) with SessionStart/PreCompact hooks and repository instructions (.github/copilot-instructions.md).

Co-authored-by: Julian Palmerio <julianpalmerio@hotmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-05-14 10:51:38 -07:00

586 lines
20 KiB
Markdown

# Setup Command Reference
Last reviewed: 2026-05-08
Freshness source: `cmd/bd/setup*.go` and `internal/recipes/`.
**For:** Setting up beads integration with AI coding tools
**Version:** current CLI behaviour; verify recipe lists against the freshness
source above.
## Overview
The `bd setup` command uses a **recipe-based architecture** to configure beads integration with AI coding tools. Recipes define where workflow instructions are written—built-in recipes handle popular tools, and you can add custom recipes for any tool.
### `bd prime` as SSOT
`bd prime` is the **single source of truth** for operational workflow commands. The beads section in each tool's instruction file provides a pointer to `bd prime` for hook-enabled agents (Claude, Gemini) or the full command reference for AGENTS-first agents (Factory, Mux). Codex uses a Beads skill plus generated `AGENTS.md` guidance that points Codex at that skill.
### Profiles
Each integration uses one of two **profiles** that control how much content is written to tool instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`):
| Profile | Used By | Content |
|---------|---------|---------|
| `full` | Factory, Codex, Mux, OpenCode | Complete command reference, issue types, priorities, workflow |
| `minimal` | Claude Code, GitHub Copilot CLI, Gemini CLI | Pointer to `bd prime`, quick reference only (~60% smaller) |
Hook-enabled agents (Claude, Copilot CLI, Gemini) use the `minimal` profile because `bd prime` injects full context at session start. AGENTS-first agents use the `full` profile because their instruction file remains the primary integration surface. Skill-aware agents use `.agents/skills/beads/SKILL.md`, with project `AGENTS.md` or global `$CODEX_HOME/AGENTS.md`/`~/.codex/AGENTS.md` telling Codex when to use the skill.
**Profile precedence:** If a file already has a `full` profile section and a `minimal` profile tool installs to the same file (e.g., via symlinks), the `full` profile is preserved to avoid information loss.
### Built-in Recipes
| Recipe | Path | Integration Type |
|--------|------|-----------------|
| `cursor` | `.cursor/rules/beads.mdc` | Rules file |
| `windsurf` | `.windsurf/rules/beads.md` | Rules file |
| `cody` | `.cody/rules/beads.md` | Rules file |
| `kilocode` | `.kilocode/rules/beads.md` | Rules file |
| `claude` | `~/.claude/settings.json` + `CLAUDE.md` | SessionStart/PreCompact hooks + minimal section |
| `copilot` | `.copilot-plugin/plugin.json` + `.github/copilot-instructions.md` | native Copilot plugin hooks + repository instructions |
| `gemini` | `~/.gemini/settings.json` + `GEMINI.md` | SessionStart/PreCompress hooks + minimal section |
| `factory` | `AGENTS.md` | Marked section |
| `codex` | `.agents/skills/beads/SKILL.md` + `AGENTS.md` | Beads agent skill + generated skill guidance |
| `mux` | `AGENTS.md` | Marked section |
| `aider` | `.aider.conf.yml` + `.aider/` | Multi-file config |
## Quick Start
```bash
# List all available recipes
bd setup --list
# Install integration for your tool
bd setup cursor # Cursor IDE
bd setup windsurf # Windsurf
bd setup kilocode # Kilo Code
bd setup claude # Claude Code
bd setup copilot # GitHub Copilot CLI plugin + instructions
bd setup gemini # Gemini CLI
bd setup factory # Factory.ai Droid
bd setup codex # Beads agent skill + AGENTS.md guidance
bd setup mux # Mux
bd setup aider # Aider
# Verify installation
bd setup cursor --check
bd setup claude --check
# Print template to stdout (for inspection)
bd setup --print
# Write template to custom path
bd setup -o .my-editor/rules.md
# Add a custom recipe
bd setup --add myeditor .myeditor/rules.md
bd setup myeditor # Now you can use it
```
## Factory.ai (Droid)
Factory.ai Droid integration uses the AGENTS.md standard, which is compatible with multiple AI coding assistants.
### Installation
```bash
# Create or update AGENTS.md with beads integration
bd setup factory
```
### What Gets Installed
Creates or updates `AGENTS.md` in your project root with:
- Issue tracking workflow instructions
- Quick command reference
- Issue types and priorities
- Dolt remote sync explanation
- Important rules for AI agents
The beads section is wrapped in HTML comments (`<!-- BEGIN/END BEADS INTEGRATION -->`) with metadata for safe updates. The begin marker includes profile and hash metadata (e.g., `<!-- BEGIN BEADS INTEGRATION profile:full hash:d4f96305 -->`) for freshness detection. Legacy markers without metadata are auto-upgraded on the next install or update.
### AGENTS.md Standard
AGENTS.md is an industry-standard format for AI coding agent instructions, supported by:
- **Factory.ai Droid** - Specialized coding agents
- **Cursor** - Also reads AGENTS.md (in addition to .cursor/rules)
- **Aider** - Can be configured to read AGENTS.md
- **Gemini CLI** - Google's command-line AI assistant
- **Jules** - Google's coding assistant
- **Codex** - OpenAI's code generation model
- **Zed** - AI-enhanced editor
- And many more emerging tools
Using AGENTS.md means one configuration file works across your entire AI tool ecosystem.
### Flags
| Flag | Description |
|------|-------------|
| `--check` | Check if beads section exists and is current (reports `missing`, `stale`, or `current`) |
| `--remove` | Remove beads section from AGENTS.md |
### Examples
```bash
# Check if beads section is in AGENTS.md
bd setup factory --check
# Output: ✓ Factory.ai integration installed: AGENTS.md
# Beads section found in AGENTS.md
# Remove beads section
bd setup factory --remove
```
### How It Works
Factory Droid and other AGENTS.md-compatible tools automatically read `AGENTS.md` from:
1. Current working directory (`./AGENTS.md`)
2. Parent directories up to repo root
3. Personal override (`~/.factory/AGENTS.md`)
The beads section teaches AI agents:
- To use `bd ready` for finding work
- To use `bd create` for tracking new issues
- To use `bd dolt push` at session end
- The complete workflow pattern and best practices
### Updating Existing AGENTS.md
If you already have an AGENTS.md file with other project instructions:
- `bd setup factory` will **append** the beads section
- Re-running it will **update** the existing beads section (idempotent)
- The markers (`<!-- BEGIN/END BEADS INTEGRATION -->`) ensure safe updates
### When to Use This vs Other Integrations
**Use Factory integration when:**
- ✅ You use Factory.ai Droid
- ✅ You want one config file for multiple AI tools
- ✅ You prefer the AGENTS.md standard
- ✅ Your team uses multiple AI coding assistants
**Use other integrations when:**
- ✅ You only use Claude Code → `bd setup claude` (hooks are more dynamic)
- ✅ You need tool-specific features (like Claude's stealth mode)
You can use multiple integrations simultaneously - they complement each other!
## Codex CLI
Codex reads project instructions from `AGENTS.md` in the current working directory or project root, and global instructions from `$CODEX_HOME/AGENTS.md` when `CODEX_HOME` is set, otherwise `~/.codex/AGENTS.md`. The Codex setup path installs the generic `beads` agent skill and writes a managed section to the Codex-readable instruction file telling Codex to use that skill for Beads workflow guidance.
### Installation
```bash
bd setup codex # Project Beads skill + AGENTS.md guidance
bd setup codex --global # Global Beads skill + global AGENTS.md guidance
```
### What Gets Installed
**Project install** (`bd setup codex`):
- Creates or updates `.agents/skills/beads/SKILL.md`
- Creates or updates `.agents/skills/beads/agents/openai.yaml`
- Creates or updates project `AGENTS.md` with a marked section generated by `bd setup codex`
**Global install** (`bd setup codex --global`):
- Creates or updates `~/.agents/skills/beads/SKILL.md`
- Creates or updates `~/.agents/skills/beads/agents/openai.yaml`
- Creates or updates `$CODEX_HOME/AGENTS.md` when `CODEX_HOME` is set, otherwise `~/.codex/AGENTS.md`, with a marked section generated by `bd setup codex --global`
### Flags
| Flag | Description |
|------|-------------|
| `--check` | Check the Beads agent skill and managed Codex `AGENTS.md` guidance |
| `--remove` | Remove the Beads agent skill and managed Codex `AGENTS.md` guidance |
| `--global` | Install/check/remove the global skill and global Codex `AGENTS.md` guidance |
### Notes
- Restart Codex if it's already running to pick up the new instructions.
- The plugin package under `plugins/beads/` is separate from `bd setup codex`. The setup command writes a small setup-only skill and managed guidance into the target repository or user-level `.agents` directory.
- In worktree/shared/`BEADS_DIR` setups, use `bd where` to confirm the resolved workspace; the integration does not require a local `./.beads`.
- `bd setup codex` uses its own marker pair (`BEGIN/END BEADS CODEX SETUP`), distinct from the `BEGIN/END BEADS INTEGRATION` markers used by `bd setup factory` and `bd setup mux`. Running both `bd setup codex` and `bd setup factory`/`mux` against the same `AGENTS.md` will leave two managed sections side by side; each `bd setup … --check` only inspects its own section, and `bd setup … --remove` only removes its own section.
## Mux
Mux reads layered instruction files, including workspace `AGENTS.md`. Adding the beads section is enough to get Mux and beads working together.
### Installation
```bash
bd setup mux # Root AGENTS.md
bd setup mux --project # Root AGENTS.md + .mux/AGENTS.md
bd setup mux --global # Root AGENTS.md + ~/.mux/AGENTS.md
```
### What Gets Installed
Creates or updates `AGENTS.md` with the beads integration section (same markers as Factory.ai and Codex).
### Notes
- Mux instruction file behavior is documented at [https://mux.coder.com/AGENTS.md](https://mux.coder.com/AGENTS.md).
- Restart the workspace session if Mux is already running.
### Flags
| Flag | Description |
|------|-------------|
| `--check` | Check root integration (and with layer flags, also check those layers) |
| `--remove` | Remove root integration (and with layer flags, also remove those layers) |
| `--project` | Install/check/remove workspace-layer instructions in `.mux/AGENTS.md` |
| `--global` | Install/check/remove global-layer instructions in `~/.mux/AGENTS.md` |
## Claude Code
Claude Code integration uses hooks to automatically inject beads workflow context at session start and before context compaction.
### Installation
```bash
# Global installation (recommended)
bd setup claude
# Project-only installation
bd setup claude --project
# With stealth mode (flush only, no git operations)
bd setup claude --stealth
```
### What Gets Installed
**Global installation** (`~/.claude/settings.json`):
- `SessionStart` hook: Runs `bd prime --hook-json` when a session starts, resumes, clears, or restarts after compaction
**Project installation** (`.claude/settings.local.json`):
- Same hooks, but only active for this project
**Instruction file** (`CLAUDE.md` in project root):
- Minimal-profile beads section pointing to `bd prime`
- Managed with hash/version markers for safe updates and `--check` freshness detection
### Flags
| Flag | Description |
|------|-------------|
| `--check` | Check both hooks and the managed `CLAUDE.md` beads section |
| `--remove` | Remove beads hooks and managed `CLAUDE.md` beads section |
| `--project` | Install for this project only (not globally) |
| `--stealth` | Use `bd prime --stealth` (flush only, no git operations) |
### Examples
```bash
# Check hooks + CLAUDE.md beads section
bd setup claude --check
# Output: ✓ Global hooks installed: /Users/you/.claude/settings.json
# ✓ Claude Code integration installed: /path/to/CLAUDE.md (current)
# Remove hooks
bd setup claude --remove
# Install project-specific hooks with stealth mode
bd setup claude --project --stealth
```
### How It Works
The hook calls `bd prime --hook-json` which:
1. Outputs workflow context wrapped in the SessionStart JSON envelope Claude Code expects
2. Prints persistent memories near the top so hook-output previews do not hide them
3. Starts with a truncation warning telling agents to read the full persisted hook output when the host caps previews
4. Ensures Claude always knows how to use beads
5. Follows resolved workspace semantics, so `bd where` is the right diagnostic check when local `./.beads` is absent
For low-token hooks that only need durable project facts, use `bd prime --memories-only`.
This is more context-efficient than MCP tools (~1-2k tokens vs 10-50k for MCP schemas).
## Gemini CLI
Gemini CLI integration uses a SessionStart hook to automatically inject beads workflow context when a session opens.
### Installation
```bash
# Global installation (recommended)
bd setup gemini
# Project-only installation
bd setup gemini --project
# With stealth mode (flush only, no git operations)
bd setup gemini --stealth
```
### What Gets Installed
**Global installation** (`~/.gemini/settings.json`):
- `SessionStart` hook: Runs `bd prime --hook-json` when a new session starts, wrapped in the JSON envelope Gemini's hook contract requires
**Project installation** (`.gemini/settings.json`):
- Same hooks, but only active for this project
**Instruction file** (`GEMINI.md` in project root):
- Minimal-profile beads section pointing to `bd prime`
- Managed with hash/version markers for safe updates and `--check` freshness detection
### Flags
| Flag | Description |
|------|-------------|
| `--check` | Check both hooks and the managed `GEMINI.md` beads section |
| `--remove` | Remove beads hooks and managed `GEMINI.md` beads section |
| `--project` | Install for this project only (not globally) |
| `--stealth` | Use `bd prime --stealth` (flush only, no git operations) |
### Examples
```bash
# Check hooks + GEMINI.md beads section
bd setup gemini --check
# Output: ✓ Global hooks installed: /Users/you/.gemini/settings.json
# ✓ Gemini CLI integration installed: /path/to/GEMINI.md (current)
# Remove hooks
bd setup gemini --remove
# Install project-specific hooks with stealth mode
bd setup gemini --project --stealth
```
### How It Works
The hooks call `bd prime` which:
1. Outputs workflow context for Gemini to read
2. Prints persistent memories near the top so hook-output previews do not hide them
3. Starts with a truncation warning telling agents to read the full persisted hook output when the host caps previews
4. Ensures Gemini always knows how to use beads
For low-token hooks that only need durable project facts, use `bd prime --memories-only`.
This works similarly to Claude Code integration, using Gemini CLI's hook system (SessionStart event). Unlike Claude Code, Gemini requires hook stdout to be valid JSON — `bd prime --hook-json` wraps the markdown in the required envelope.
## Cursor IDE
Cursor integration creates a rules file that provides beads workflow context to the AI.
### Installation
```bash
bd setup cursor
```
### What Gets Installed
Creates `.cursor/rules/beads.mdc` with:
- Core workflow rules (track work in bd, not markdown TODOs)
- Quick command reference
- Workflow pattern (ready → claim → work → close → sync)
- Context loading instructions
### Flags
| Flag | Description |
|------|-------------|
| `--check` | Check if integration is installed |
| `--remove` | Remove beads rules file |
### Examples
```bash
# Check if rules are installed
bd setup cursor --check
# Output: ✓ Cursor integration installed: .cursor/rules/beads.mdc
# Remove rules
bd setup cursor --remove
```
### How It Works
Cursor reads `.cursor/rules/*.mdc` files and includes them in the AI's context. The beads rules file teaches the AI:
- To use `bd ready` for finding work
- To use `bd create` for tracking new issues
- To use `bd dolt push` at session end
- The basic workflow pattern
## Aider
Aider integration creates configuration files that teach the AI about beads, while respecting Aider's human-in-the-loop design.
### Installation
```bash
bd setup aider
```
### What Gets Installed
| File | Purpose |
|------|---------|
| `.aider.conf.yml` | Points Aider to read the instructions file |
| `.aider/BEADS.md` | Workflow instructions for the AI |
| `.aider/README.md` | Quick reference for humans |
### Flags
| Flag | Description |
|------|-------------|
| `--check` | Check if integration is installed |
| `--remove` | Remove beads configuration |
### Examples
```bash
# Check if config is installed
bd setup aider --check
# Output: ✓ Aider integration installed: .aider.conf.yml
# Remove configuration
bd setup aider --remove
```
### How It Works
Unlike Claude Code, Aider requires explicit command execution. The AI will **suggest** bd commands, which the user runs via `/run`:
```
You: What issues are ready to work on?
Aider: Let me check. Run:
/run bd ready
You: [runs the command]
Aider: Great! To claim bd-42, run:
/run bd update bd-42 --claim
```
This respects Aider's philosophy of keeping humans in control while still leveraging beads for issue tracking.
## Comparison
| Feature | Factory.ai | Codex | Mux | Claude Code | Gemini CLI | Cursor | Aider |
|---------|-----------|-------|-----|-------------|------------|--------|-------|
| Command execution | Automatic | Automatic | Automatic | Automatic | Automatic | Automatic | Manual (/run) |
| Context injection | AGENTS.md | Skill + AGENTS.md | AGENTS.md | Hooks + CLAUDE.md | Hooks + GEMINI.md | Rules file | Config file |
| Global install | No (per-project) | No (per-project) | No (per-project) | Yes | Yes | No (per-project) | No (per-project) |
| Stealth mode | N/A | N/A | N/A | Yes | Yes | N/A | N/A |
| Standard format | Yes (AGENTS.md) | Yes (AGENTS.md) | Yes (AGENTS.md) | No (proprietary) | No (proprietary) | No (proprietary) | No (proprietary) |
| Multi-tool compatible | Yes | Yes | Yes | No | No | No | No |
## Best Practices
1. **Start with Factory integration** - Creates AGENTS.md which works across multiple AI tools:
```bash
bd setup factory
```
2. **Add tool-specific integrations as needed** - Claude hooks, Cursor rules, or Aider config for tool-specific features
3. **Install globally for Claude Code or Gemini CLI** - You'll get beads context in every project automatically
4. **Use stealth mode in CI/CD** - `bd setup claude --stealth` or `bd setup gemini --stealth` avoids git operations that might fail in automated environments
5. **Commit instruction files to git** - This ensures all team members and AI tools get the same instructions (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, as applicable)
6. **Run `bd doctor` after setup** - Verifies the integration is working:
```bash
bd doctor | grep -iE "claude|gemini"
# Claude Integration: Hooks installed (CLI mode)
# Gemini CLI Integration: Hooks installed
```
## Troubleshooting
### "Hooks not working"
1. Restart your AI tool after installation
2. Verify with `bd setup <tool> --check`
3. Check `bd doctor` output for integration status
### "Context not appearing"
For Claude Code, ensure `bd prime` works standalone:
```bash
bd prime
```
If this fails, fix the underlying beads issue first.
### "Want to switch from global to project hooks"
```bash
# Remove global hooks
bd setup claude --remove
# Install project hooks
bd setup claude --project
```
## Custom Recipes
You can add custom recipes for editors/tools not included in the built-in list.
### Adding a Custom Recipe
```bash
# Add a recipe that writes to a specific path
bd setup --add myeditor .myeditor/rules.md
# Install it
bd setup myeditor
# Check it
bd setup myeditor --check
# Remove it
bd setup myeditor --remove
```
### User Recipes File
Custom recipes are stored in `.beads/recipes.toml`:
```toml
[recipes.myeditor]
name = "myeditor"
path = ".myeditor/rules.md"
type = "file"
```
### Using Arbitrary Paths
For one-off installs without saving a recipe:
```bash
# Write template to any path
bd setup -o .my-custom-location/beads.md
# Inspect the template first
bd setup --print
```
### Recipe Types
| Type | Description | Example |
|------|-------------|---------|
| `file` | Write template to a single file | cursor, windsurf, cody, kilocode |
| `hooks` | Modify JSON settings to add hooks | claude, gemini |
| `section` | Inject marked section into existing file | factory |
| `multifile` | Write multiple files | aider |
Custom recipes added via `--add` are always type `file`.
## Related Documentation
- [CLAUDE_INTEGRATION.md](CLAUDE_INTEGRATION.md) - Design decisions for Claude Code integration
- [AIDER_INTEGRATION.md](AIDER_INTEGRATION.md) - Detailed Aider workflow guide
- [QUICKSTART.md](QUICKSTART.md) - Getting started with beads
- [CLI_REFERENCE.md](CLI_REFERENCE.md) - Full command reference