Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
3.7 KiB
| title |
|---|
| IDE Setup |
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