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

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
```