beads/npm-package/INTEGRATION_GUIDE.md
Ben Madore 3b39ce577a
docs: update user-facing URLs from steveyegge/beads to gastownhall/beads
Co-authored-by: Ben Madore <823868+madorb@users.noreply.github.com>
2026-04-24 08:17:42 -07:00

8.8 KiB

Complete Integration Guide: @beads/bd + Claude Code for Web

This guide shows the complete end-to-end setup for using bd (beads) in Claude Code for Web via the npm package.

🎯 Goal

Enable automatic issue tracking with bd in every Claude Code for Web session with zero manual setup.

📋 Prerequisites

  • A git repository with your project
  • Claude Code for Web access

🚀 Quick Setup (5 Minutes)

Step 1: Create SessionStart Hook

Create the file .claude/hooks/session-start.sh in your repository:

#!/bin/bash
# Auto-install bd in every Claude Code for Web session

# Install bd globally from npm
npm install -g @beads/bd

# Initialize bd if not already done
if [ ! -d .beads ]; then
  bd init --quiet
fi

# Show current work
echo ""
echo "📋 Ready work:"
bd ready --limit 5 || echo "No ready work found"

Step 2: Make Hook Executable

chmod +x .claude/hooks/session-start.sh

Step 3: Update AGENTS.md

Add bd usage instructions to your AGENTS.md file:

## Issue Tracking with bd

This project uses bd (beads) for issue tracking. It's automatically installed in each session via SessionStart hook.

### Finding Work

```bash
# See what's ready to work on
bd ready --json | jq '.[0]'

# Get issue details
bd show <issue-id> --json

Creating Issues

# Create a new issue
bd create "Task description" -t task -p 1 --json

# Create a bug
bd create "Bug description" -t bug -p 0 --json

Working on Issues

# Start work (atomic claim)
bd update <issue-id> --claim

# Add a comment
bd comments add <issue-id> "Progress update"

# Close when done
bd close <issue-id> --reason "Description of what was done"

Managing Dependencies

# Issue A blocks issue B
bd dep add <issue-b> <issue-a>

# Show dependency tree
bd dep tree <issue-id>

Best Practices

  1. Always use --json: Makes output easy to parse programmatically
  2. Create issues proactively: When you notice work, file it immediately
  3. Link discovered work: Use bd dep add --type discovered-from
  4. Close with context: Always provide --reason when closing
  5. Sync changes: Run bd dolt push to push changes to the Dolt remote

### Step 4: Commit and Push

```bash
git add .claude/hooks/session-start.sh AGENTS.md
git commit -m "Add bd auto-install for Claude Code for Web"
git push

🎬 How It Works

First Session in Claude Code for Web

  1. Session starts → Claude Code for Web creates fresh Linux VM
  2. Hook runs → .claude/hooks/session-start.sh executes automatically
  3. npm install → Downloads @beads/bd package from npm
  4. Postinstall → Downloads native bd binary for platform (~17MB)
  5. bd init → Sets up the .beads directory and Dolt database
  6. Ready → bd command is available, shows ready work

Time: ~5-10 seconds

Subsequent Sessions

Same process, but:

  • bd init --quiet sets up Dolt and syncs existing data
  • Agent picks up right where it left off

Time: ~5-10 seconds

💡 Usage Patterns

Pattern 1: Agent Starts Session

Agent: Starting new session...
System: Running SessionStart hook...
System: Installing bd v0.21.5...
System: ✓ bd installed successfully
System:
System: 📋 Ready work:
System: bd-a1b2 [P1] Fix authentication bug
System: bd-f14c [P1] Add user profile page
System:
Agent: I can see there are 2 ready tasks. Let me work on bd-a1b2 (Fix authentication bug).
Agent: [runs] bd update bd-a1b2 --claim

Pattern 2: Discovering New Work

Agent: While fixing bd-a1b2, I noticed the password reset flow is also broken.
Agent: [runs] bd create "Fix password reset flow" -t bug -p 1 --json
System: {"id": "bd-3e7a", ...}
Agent: [runs] bd dep add bd-3e7a bd-a1b2 --type discovered-from
Agent: I've filed bd-3e7a for the password reset issue and linked it to the current work.

Pattern 3: Completing Work

Agent: I've fixed the authentication bug. Tests are passing.
Agent: [runs] bd close bd-a1b2 --reason "Fixed session validation logic. Added tests."
Agent: [runs] git add . && git commit -m "Fix authentication bug (bd-a1b2)"
Agent: Work completed. Ready for next task.

🔧 Advanced Configuration

Custom Installation Path

Install to project instead of global:

#!/bin/bash
# .claude/hooks/session-start.sh

# Install as project dependency
npm install --save-dev @beads/bd

# Use via npx
npx bd init --quiet

echo "Use 'npx bd' for all bd commands"

Conditional Installation

Only install if not already present:

#!/bin/bash
# .claude/hooks/session-start.sh

if ! command -v bd &> /dev/null; then
    echo "Installing bd..."
    npm install -g @beads/bd
else
    echo "bd already available: $(bd version)"
fi

# Rest of setup...

Silent Installation

Minimal output for cleaner logs:

#!/bin/bash
# .claude/hooks/session-start.sh

npm install -g @beads/bd --silent 2>&1 | grep -v "npm WARN"
bd init --quiet 2>&1 | grep -v "already initialized"

📊 Benefits

For Agents

  • ✅ Persistent memory: Issue context survives session resets
  • ✅ Structured planning: Dependencies create clear work order
  • ✅ Automatic setup: No manual intervention needed
  • ✅ Dolt-backed: All issues are version controlled
  • ✅ Fast queries: bd ready finds work instantly

For Humans

  • ✅ Visibility: See what agents are working on
  • ✅ Auditability: Full history of issue changes
  • ✅ Collaboration: Multiple agents share same issue database
  • ✅ Portability: Works locally and in cloud sessions
  • ✅ No servers: Everything is git and SQLite

vs Markdown TODOs

Feature bd Issues Markdown TODOs
Dependencies ✅ 4 types ❌ None
Ready work detection ✅ Automatic ❌ Manual
Status tracking ✅ Built-in ❌ Manual
History/audit ✅ Full trail ❌ Git only
Queries ✅ SQL-backed ❌ Text search
Cross-session ✅ Persistent ⚠️ Markdown only
Agent-friendly ✅ JSON output ⚠️ Parsing required

🐛 Troubleshooting

"bd: command not found"

Cause: SessionStart hook didn't run or installation failed

Fix:

# Manually install
npm install -g @beads/bd

# Verify
bd version

"Database not found"

Cause: bd init wasn't run

Fix:

bd init

"Merge conflict during sync"

Cause: Two sessions modified issues concurrently

Fix: Run bd dolt pull to resolve via Dolt's merge. See the main beads TROUBLESHOOTING.md for details.

Slow Installation

Cause: Network latency downloading binary

Optimize:

# Use npm cache
npm config set cache ~/.npm-cache

# Or install as dependency (cached by package-lock.json)
npm install --save-dev @beads/bd

📚 Next Steps

  1. Read the full docs: https://github.com/gastownhall/beads
  2. Try the quickstart: bd quickstart (interactive tutorial)
  3. Set up MCP: For local Claude Desktop integration
  4. Explore examples: https://github.com/gastownhall/beads/tree/main/examples

🔗 Resources

💬 Example Agent Prompt

Add this to your project's system prompt or AGENTS.md:

You have access to bd (beads) for issue tracking. It's automatically installed in each session.

WORKFLOW:
1. Start each session: Check `bd ready --json` for available work
2. Choose a task: Pick highest priority with no blockers
3. Start work: `bd update <id> --claim`
4. Work on it: Implement, test, document
5. File new issues: Create issues for any work discovered
6. Link issues: Use `bd dep add` to track relationships
7. Close when done: `bd close <id> --reason "what you did"`
8. Sync changes: Run `bd dolt push` at end of session

ALWAYS:
- Use --json flags for programmatic parsing
- Create issues proactively (don't let work be forgotten)
- Link related issues with dependencies
- Close issues with descriptive reasons
- Run `bd dolt push` at end of sessions

NEVER:
- Use markdown TODOs (use bd instead)
- Work on blocked issues (check `bd show <id>` for blockers)
- Close issues without --reason
- Forget to run `bd dolt push` at end of sessions

🎉 Success Criteria

After setup, you should see:

✅ New sessions automatically have bd available ✅ Agents use bd for all issue tracking ✅ Issues persist across sessions via git ✅ Multiple agents can collaborate on same issues ✅ No manual installation required

🆘 Support