* 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>
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 primewhen Claude Code starts - SessionStart compact refresh - Runs
bd primeafter context compaction
How it works:
- SessionStart hook runs
bd primeautomatically bd primeinjects ~1-2k tokens of workflow context- You use
bdCLI commands directly - 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