npm-package/CLAUDE_CODE_WEB.md
This guide shows how to automatically install and use bd (beads issue tracker) in Claude Code for Web sessions using SessionStart hooks.
Claude Code for Web provides full Linux VM sandboxes with npm support. Each session is a fresh environment, so tools need to be installed at the start of each session.
Claude Code for Web environments:
The @beads/bd npm package solves this by:
Create or edit .claude/hooks/session-start.sh in your project:
#!/bin/bash
# .claude/hooks/session-start.sh
# Install bd globally (only takes a few seconds)
echo "Installing bd (beads issue tracker)..."
npm install -g @beads/bd
# Initialize bd in the project (if not already initialized)
if [ ! -d .beads ]; then
bd init --quiet
fi
echo "✓ bd is ready! Use 'bd ready' to see available work."
Make it executable:
chmod +x .claude/hooks/session-start.sh
If you prefer not to use hooks, you can manually install at the start of each session:
npm install -g @beads/bd
bd init --quiet
Install as a dev dependency (slower but doesn't require global install):
npm install --save-dev @beads/bd
# Use with npx
npx bd version
npx bd ready
After installation, verify bd is working:
# Check version
bd version
# Check database info
bd info
# See what work is ready
bd ready --json
Once installed, bd works identically to the native version:
# Create issues
bd create "Fix authentication bug" -t bug -p 1
# View ready work
bd ready
# Start work
bd update bd-a1b2 --claim
# Add dependencies
bd dep add bd-f14c bd-a1b2
# Close issues
bd close bd-a1b2 --reason "Fixed"
Tell your agent to use bd by adding to your AGENTS.md or project instructions:
## Issue Tracking
Use the `bd` command for all issue tracking instead of markdown TODOs:
- Create issues: `bd create "Task description" -p 1 --json`
- Find work: `bd ready --json`
- Start work: `bd update <id> --claim --json`
- View details: `bd show <id> --json`
Use `--json` flags for programmatic parsing.
bd command is a Node.js wrapper that invokes the native binaryThe SessionStart hook didn't run or installation failed. Manually run:
npm install -g @beads/bd
Some Claude Code web environments have network restrictions that prevent the npm postinstall script from downloading the binary. You'll see errors like:
Error installing bd: getaddrinfo EAI_AGAIN github.com
or
curl: (22) The requested URL returned error: 403
Workaround: Use go install
If Go is available (it usually is in Claude Code web), use the go install fallback:
# Install via go
go install github.com/steveyegge/beads/cmd/bd@latest
# Add to PATH (required each session)
export PATH="$PATH:$HOME/go/bin"
# Verify installation
bd version
SessionStart hook with go install fallback:
#!/bin/bash
# .claude/hooks/session-start.sh
echo "🔗 Setting up bd (beads issue tracker)..."
# Try npm first, fall back to go install
if ! command -v bd &> /dev/null; then
if npm install -g @beads/bd --quiet 2>/dev/null && command -v bd &> /dev/null; then
echo "✓ Installed via npm"
elif command -v go &> /dev/null; then
echo "npm install failed, trying go install..."
go install github.com/steveyegge/beads/cmd/bd@latest
export PATH="$PATH:$HOME/go/bin"
echo "✓ Installed via go install"
else
echo "✗ Installation failed - neither npm nor go available"
exit 1
fi
fi
# Verify and show version
bd version
The version in package.json doesn't match a GitHub release. This shouldn't happen with published npm packages, but if it does, check:
npm view @beads/bd versions
And install a specific version:
npm install -g @beads/[email protected]
Platform detection may have failed. Check:
node -e "console.log(require('os').platform(), require('os').arch())"
Should output something like: linux x64
The binary download may be slow depending on network conditions. The native binary is ~17MB, which should download in a few seconds on most connections.
If it's consistently slow, consider:
This npm package wraps the native bd binary rather than using WebAssembly because:
#!/bin/bash
# .claude/hooks/session-start.sh
set -e # Exit on error
echo "🔗 Setting up bd (beads issue tracker)..."
# Install bd globally
if ! command -v bd &> /dev/null; then
echo "Installing @beads/bd from npm..."
npm install -g @beads/bd --quiet
else
echo "bd already installed"
fi
# Verify installation
if bd version &> /dev/null; then
echo "✓ bd $(bd version)"
else
echo "✗ bd installation failed"
exit 1
fi
# Initialize if needed
if [ ! -d .beads ]; then
echo "Initializing bd in project..."
bd init --quiet
else
echo "bd already initialized"
fi
# Show ready work
echo ""
echo "Ready work:"
bd ready --limit 5
echo ""
echo "✓ bd is ready! Use 'bd --help' for commands."
You are working on a project that uses bd (beads) for issue tracking.
At the start of each session:
1. Run `bd ready --json` to see available work
2. Choose an issue to work on
3. Start work: `bd update <id> --claim`
While working:
- Create new issues for any bugs you discover
- Link related issues with `bd dep add`
- Add comments with `bd comments add <id> "comment text"`
When done:
- Close the issue: `bd close <id> --reason "Description of what was done"`
- Run `bd dolt push` to push issue changes
If you prefer to track bd as a project dependency instead of global install:
{
"devDependencies": {
"@beads/bd": "^0.21.5"
},
"scripts": {
"bd": "bd",
"ready": "bd ready",
"postinstall": "bd init --quiet || true"
}
}
Then use with npm scripts or npx:
npm run ready
npx bd create "New issue"