* feat(docs): version Docusaurus site and align llms-full with snapshots Add docs version 1.0.0, version dropdown, lastVersion defaulting to stable, merged markdown config, and RELEASING steps for future doc snapshots. generate-llms-full.sh reads the latest entry in versions.json. README links the published documentation site. Closes #2644 Made-with: Cursor * fix(docs): update org URLs to gastownhall and refresh 1.0.0 snapshot - Update default orgName in docusaurus.config.ts from steveyegge to gastownhall to match the repo's new home - Update hardcoded steveyegge URLs in generate-llms-full.sh - Refresh versioned_docs 1.0.0 snapshot to include quickstart changes from #3032 which merged after the original snapshot was taken - Regenerate llms-full.txt with corrected URLs and updated content Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: matt wilkie <maphew@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3 KiB
3 KiB
| id | title | sidebar_position |
|---|---|---|
| claude-code | Claude Code | 1 |
Claude Code Integration
How to use beads with Claude Code.
Setup
Quick Setup
bd setup claude
This installs:
- SessionStart hook - Runs
bd primeon session start - PreCompact hook - Runs
bd dolt pushbefore context compaction
Manual Setup
Add to your Claude Code hooks configuration:
{
"hooks": {
"SessionStart": ["bd prime"],
"PreCompact": ["bd dolt push"]
}
}
Verify Setup
bd setup claude --check
How It Works
- Session starts →
bd primeinjects ~1-2k tokens of context - You work → Use
bdCLI commands directly - Session compacts →
bd dolt pushsaves work to Dolt remote - Session ends → Changes synced via git
Essential Commands for Agents
Creating Issues
# Always include description for context
bd create "Fix authentication bug" \
--description="Login fails with special characters in password" \
-t bug -p 1 --json
# Link discovered issues
bd create "Found SQL injection" \
--description="User input not sanitized in query builder" \
--deps discovered-from:bd-42 --json
Working on Issues
# Find ready work
bd ready --json
# Start work
bd update bd-42 --claim --json
# Complete work
bd close bd-42 --reason "Fixed in commit abc123" --json
Querying
# List open issues
bd list --status open --json
# Show issue details
bd show bd-42 --json
# Check blocked issues
bd blocked --json
Syncing
# ALWAYS run at session end
bd dolt push
Best Practices
Always Use --json
bd list --json # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json # Structured data
Always Include Descriptions
# Good
bd create "Fix auth bug" \
--description="Login fails when password contains quotes" \
-t bug -p 1 --json
# Bad - no context for future work
bd create "Fix auth bug" -t bug -p 1 --json
Link Related Work
# When you discover issues during work
bd create "Found related bug" \
--deps discovered-from:bd-current --json
Push Before Session End
# ALWAYS run before ending
bd dolt push
Plugin (Optional)
For enhanced UX with slash commands:
# In Claude Code
/plugin marketplace add steveyegge/beads
/plugin install beads
# Restart Claude Code
Adds slash commands:
/beads:ready- Show ready work/beads:create- Create issue/beads:show- Show issue/beads:update- Update issue/beads:close- Close issue
Troubleshooting
Context not injected
# Check hook setup
bd setup claude --check
# Manually prime
bd prime
Changes not syncing
# Force push
bd dolt push
# Check system health
bd doctor
Database not found
# Initialize beads
bd init --quiet
See Also
- MCP Server - For MCP-only environments
- IDE Setup - Other editors