beads/website/docs/getting-started/ide-setup.md
matt wilkie 0c47b3c5ac
fix(init): use git origin as default Dolt remote (#3909)
* fix(init): wire git origin as Dolt remote

Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync.

Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only.

_codex-gpt-5-xhigh on behalf of maphew_

* test: keep embedded command stderr out of parsed stdout

Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_

---------

Co-authored-by: CI Bot <ci@beads.test>
2026-05-13 07:02:39 -07:00

3.8 KiB

id title sidebar_position
ide-setup IDE Setup 3

IDE Setup for AI Agents

Configure your IDE for optimal beads integration.

Claude Code

The recommended approach for Claude Code:

# Setup Claude Code integration
bd setup claude

This installs:

  • SessionStart hook - Runs bd prime when Claude Code starts
  • SessionStart compact refresh - Runs bd prime after context compaction

How it works:

  1. SessionStart hook runs bd prime automatically
  2. bd prime injects ~1-2k tokens of workflow context
  3. You use bd CLI commands directly
  4. Git hooks refresh exports and legacy fallbacks; Dolt remotes handle sync

Verify installation:

bd setup claude --check

Manual Setup

If you prefer manual configuration, add to your Claude Code hooks:

{
  "hooks": {
    "SessionStart": ["bd prime"],
    "SessionStart": ["bd prime"]
  }
}

Cursor IDE

# Setup Cursor integration
bd setup cursor

This creates .cursor/rules/beads.mdc with beads-aware rules.

Verify:

bd setup cursor --check

Aider

# Setup Aider integration
bd setup aider

This creates/updates .aider.conf.yml with beads context.

Verify:

bd setup aider --check

GitHub Copilot

For VS Code with GitHub Copilot, use the MCP server:

# Install MCP server
uv tool install beads-mcp

Create .vscode/mcp.json in your project:

{
  "servers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

For all projects: Add to VS Code user-level MCP config:

Platform Path
macOS ~/Library/Application Support/Code/User/mcp.json
Linux ~/.config/Code/User/mcp.json
Windows %APPDATA%\Code\User\mcp.json
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}

Initialize beads and reload VS Code:

bd init --quiet

See GitHub Copilot Integration for detailed setup.

Context Injection with bd prime

All integrations use bd prime to inject context:

bd prime

This outputs a compact (~1-2k tokens) workflow reference including:

  • Available commands
  • Current project status
  • Workflow patterns
  • Best practices
  • Persistent memories from bd remember

bd prime prints memories near the top and starts with a truncation warning. If your host stores the full hook output in a file and only shows a preview, have the agent read the full file before continuing.

For memory-only hooks:

bd prime --memories-only

Why context efficiency matters:

  • Compute cost scales with tokens
  • Latency increases with context size
  • Models attend better to smaller, focused contexts

MCP Server (Alternative)

For MCP-only environments (Claude Desktop, no shell access):

# Install MCP server
pip install beads-mcp

Add to Claude Desktop config:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

Trade-offs:

  • Works in MCP-only environments
  • Higher context overhead (10-50k tokens for tool schemas)
  • Additional latency from MCP protocol

See MCP Server for detailed configuration.

Git Hooks

Ensure git hooks are installed for export refresh and legacy fallback behavior:

bd hooks install

This installs:

  • pre-commit - Validates changes before commit
  • post-merge - Imports changes after pull
  • pre-push - Ensures sync before push

Check hook status:

bd info  # Shows warnings if hooks are outdated

Verifying Your Setup

Run a complete health check:

# Check version
bd version

# Check project health
bd doctor

# Check hooks
bd hooks status

# Check editor integration
bd setup claude --check   # or cursor, aider