beads/website/docs/integrations/claude-code.md
Amp a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
Systematic cleanup of stale documentation references left over from the
Dolt migration:

- Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files
- Replace all 'bd import' → 'bd init --from-jsonl' or remove
- Replace 'bd init --branch' → note about refs/dolt/data separation
- Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly)
- Fix npm-package, claude-plugin, integrations, examples, website docs

Add scripts/check-doc-flags.sh to catch stale doc references:
- Checks for removed commands (bd sync, bd import)
- Checks for removed flags (bd init --branch)
- Warns on legacy SQLite/beads.db references
- Compares CLI_REFERENCE.md against bd help --all

Add CI job (check-doc-flags) and Makefile target (check-docs) to gate
PRs against doc freshness.

Prior art: feat/help-doc-generator branch has bd help --doc/--list for
generating docs FROM CLI output. This script validates docs AGAINST CLI
output — complementary approaches.

Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 13:25:40 -07:00

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 prime on session start
  • PreCompact hook - Runs bd dolt push before 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

  1. Session starts → bd prime injects ~1-2k tokens of context
  2. You work → Use bd CLI commands directly
  3. Session compacts → bd dolt push saves work to Dolt remote
  4. 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
# 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