beads/npm-package/INTEGRATION_GUIDE.md

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

# Update status to in_progress
bd update <issue-id> --status in_progress

# 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. Commit .beads/: The .beads/issues.jsonl file should be committed to git

### 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 → Imports existing issues from .beads/issues.jsonl in git
6. Ready → bd command is available, shows ready work

Time: ~5-10 seconds

Subsequent Sessions

Same process, but:

• Git clone pulls existing .beads/issues.jsonl
• bd init --quiet imports all existing issues
• 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 --status in_progress

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
• ✅ Git-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

"Issues.jsonl merge conflict"

Cause: Two sessions modified issues concurrently

Fix: See the main beads TROUBLESHOOTING.md for merge resolution

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/steveyegge/beads
2. Try the quickstart: bd quickstart (interactive tutorial)
3. Set up MCP: For local Claude Desktop integration
4. Explore examples: https://github.com/steveyegge/beads/tree/main/examples

🔗 Resources

• beads GitHub
• npm package
• Claude Code docs
• SessionStart hooks

💬 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. Update status: `bd update <id> --status in_progress`
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. Commit changes: Include .beads/issues.jsonl in commits

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
- Commit .beads/issues.jsonl with code changes

NEVER:
- Use markdown TODOs (use bd instead)
- Work on blocked issues (check `bd show <id>` for blockers)
- Close issues without --reason
- Forget to commit .beads/issues.jsonl

🎉 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

• File an issue
• Read the FAQ
• Check troubleshooting