* 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>
213 lines
3.8 KiB
Markdown
213 lines
3.8 KiB
Markdown
---
|
|
id: ide-setup
|
|
title: IDE Setup
|
|
sidebar_position: 3
|
|
---
|
|
|
|
# IDE Setup for AI Agents
|
|
|
|
Configure your IDE for optimal beads integration.
|
|
|
|
## Claude Code
|
|
|
|
The recommended approach for Claude Code:
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
bd setup claude --check
|
|
```
|
|
|
|
### Manual Setup
|
|
|
|
If you prefer manual configuration, add to your Claude Code hooks:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"SessionStart": ["bd prime"],
|
|
"SessionStart": ["bd prime"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Cursor IDE
|
|
|
|
```bash
|
|
# Setup Cursor integration
|
|
bd setup cursor
|
|
```
|
|
|
|
This creates `.cursor/rules/beads.mdc` with beads-aware rules.
|
|
|
|
**Verify:**
|
|
```bash
|
|
bd setup cursor --check
|
|
```
|
|
|
|
## Aider
|
|
|
|
```bash
|
|
# Setup Aider integration
|
|
bd setup aider
|
|
```
|
|
|
|
This creates/updates `.aider.conf.yml` with beads context.
|
|
|
|
**Verify:**
|
|
```bash
|
|
bd setup aider --check
|
|
```
|
|
|
|
## GitHub Copilot
|
|
|
|
For VS Code with GitHub Copilot, use the MCP server:
|
|
|
|
```bash
|
|
# Install MCP server
|
|
uv tool install beads-mcp
|
|
```
|
|
|
|
Create `.vscode/mcp.json` in your project:
|
|
|
|
```json
|
|
{
|
|
"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` |
|
|
|
|
```json
|
|
{
|
|
"servers": {
|
|
"beads": {
|
|
"command": "beads-mcp",
|
|
"args": []
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Initialize beads and reload VS Code:
|
|
|
|
```bash
|
|
bd init --quiet
|
|
```
|
|
|
|
See [GitHub Copilot Integration](/integrations/github-copilot) for detailed setup.
|
|
|
|
## Context Injection with `bd prime`
|
|
|
|
All integrations use `bd prime` to inject context:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
# Install MCP server
|
|
pip install beads-mcp
|
|
```
|
|
|
|
Add to Claude Desktop config:
|
|
```json
|
|
{
|
|
"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](/integrations/mcp-server) for detailed configuration.
|
|
|
|
## Git Hooks
|
|
|
|
Ensure git hooks are installed for export refresh and legacy fallback behavior:
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
bd info # Shows warnings if hooks are outdated
|
|
```
|
|
|
|
## Verifying Your Setup
|
|
|
|
Run a complete health check:
|
|
|
|
```bash
|
|
# Check version
|
|
bd version
|
|
|
|
# Check project health
|
|
bd doctor
|
|
|
|
# Check hooks
|
|
bd hooks status
|
|
|
|
# Check editor integration
|
|
bd setup claude --check # or cursor, aider
|
|
```
|