johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add npm package for bd with native binaries (bd-febc)

Browse Source 
Implements @beads/bd npm package for easy installation in Node.js
environments, especially Claude Code for Web.

Features:
- Automatic platform-specific binary download during postinstall
- CLI wrapper that invokes native bd binary
- Full feature parity with standalone bd
- Works with SessionStart hooks for auto-installation

Package structure:
- bin/bd.js: Node.js CLI wrapper
- scripts/postinstall.js: Downloads correct binary from GitHub releases
- scripts/test.js: Verification tests
- Comprehensive documentation (6 guides)

Published to npm: https://www.npmjs.com/package/@beads/bd

Benefits vs WASM:
- Full SQLite support (no custom VFS)
- Better performance (native vs WASM)
- Simpler implementation and maintenance
- All commands work identically

Closes bd-febc, bd-be7a, bd-e2e6, bd-f282, bd-87a0, bd-b54c

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-11-03 11:41:18 -08:00
parent e7be0a2869
commit da921e1829
15 changed files with 1741 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

353
npm-package/INTEGRATION_GUIDE.md Normal file
View File

@@ -0,0 +1,353 @@
# 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:
```bash
#!/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
```bash
chmod +x .claude/hooks/session-start.sh
```
### Step 3: Update AGENTS.md
Add bd usage instructions to your AGENTS.md file:
```markdown
## 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
#!/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:
```bash
#!/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:
```bash
#!/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**:
```bash
# Manually install
npm install -g @beads/bd
# Verify
bd version
```
### "Database not found"
**Cause**: `bd init` wasn't run
**Fix**:
```bash
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**:
```bash
# 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](https://github.com/steveyegge/beads)
- [npm package](https://www.npmjs.com/package/@beads/bd)
- [Claude Code docs](https://docs.claude.com/claude-code)
- [SessionStart hooks](https://docs.claude.com/claude-code/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](https://github.com/steveyegge/beads/issues)
- [Read the FAQ](https://github.com/steveyegge/beads/blob/main/FAQ.md)
- [Check troubleshooting](https://github.com/steveyegge/beads/blob/main/TROUBLESHOOTING.md)