Setup beads (bd) and beads_viewer (bv) for a Claude Code project

setup-beads-project.sh

#!/bin/bash
# Setup beads (bd) and beads_viewer (bv) for a Claude Code project
# Usage: setup-beads-project.sh [project-dir]
#        Defaults to current directory if no argument provided

set -e

PROJECT_DIR="${1:-.}"
PROJECT_DIR=$(cd "$PROJECT_DIR" && pwd)

echo "Setting up beads project in: $PROJECT_DIR"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

info() { echo -e "${GREEN}[INFO]${NC} $1"; }
warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; }

# Check if command exists
command_exists() {
    command -v "$1" >/dev/null 2>&1
}

# Install beads (bd) if not present
install_bd() {
    if command_exists bd; then
        info "bd is already installed: $(bd --version 2>/dev/null || echo 'version unknown')"
        return 0
    fi

    info "Installing beads (bd)..."

    # Try npm first (most reliable)
    if command_exists npm; then
        info "Installing via npm..."
        npm install -g @beads/bd
        return $?
    fi

    # Try homebrew on macOS
    if command_exists brew; then
        info "Installing via homebrew..."
        brew install steveyegge/beads/bd
        return $?
    fi

    # Try Go
    if command_exists go; then
        info "Installing via go..."
        go install github.com/steveyegge/beads/cmd/bd@latest
        return $?
    fi

    # Fallback to shell script
    info "Installing via shell script..."
    curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
}

# Install beads_viewer (bv) if not present
install_bv() {
    if command_exists bv; then
        info "bv is already installed: $(bv --version 2>/dev/null || echo 'version unknown')"
        return 0
    fi

    info "Installing beads_viewer (bv)..."

    # Check for Go (required for bv)
    if ! command_exists go; then
        error "Go 1.21+ is required to install bv. Please install Go first:"
        echo "  - Download from: https://go.dev/dl/"
        echo "  - Or: sudo apt install golang-go"
        echo "  - Or: brew install go"
        return 1
    fi

    # Install via curl script (recommended)
    curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/main/install.sh?$(date +%s)" | bash
}

# Initialize beads in project directory
init_beads() {
    cd "$PROJECT_DIR"

    if [ -d ".beads" ]; then
        info "Beads already initialized in $PROJECT_DIR"
        return 0
    fi

    info "Initializing beads in $PROJECT_DIR..."
    bd init
}

# Add bv documentation to CLAUDE.md
setup_claude_md() {
    local CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
    local MARKER="### Using bv as an AI sidecar"

    # Create CLAUDE.md if it doesn't exist
    if [ ! -f "$CLAUDE_MD" ]; then
        info "Creating CLAUDE.md..."
        cat > "$CLAUDE_MD" << 'HEADER'
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

HEADER
    fi

    # Check if bv section already exists
    if grep -q "$MARKER" "$CLAUDE_MD" 2>/dev/null; then
        info "bv documentation already exists in CLAUDE.md"
        return 0
    fi

    info "Adding bv documentation to CLAUDE.md..."

    cat >> "$CLAUDE_MD" << 'BV_DOCS'

### Using bv as an AI sidecar

bv is a graph-aware triage engine for Beads projects (.beads/beads.jsonl). Instead of parsing JSONL or hallucinating graph traversal, use robot flags for deterministic, dependency-aware outputs with precomputed metrics (PageRank, betweenness, critical path, cycles, HITS, eigenvector, k-core).

**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (messaging, work claiming, file reservations), use [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail).

**⚠️ CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**

#### The Workflow: Start With Triage

**`bv --robot-triage` is your single entry point.** It returns everything you need in one call:
- `quick_ref`: at-a-glance counts + top 3 picks
- `recommendations`: ranked actionable items with scores, reasons, unblock info
- `quick_wins`: low-effort high-impact items
- `blockers_to_clear`: items that unblock the most downstream work
- `project_health`: status/type/priority distributions, graph metrics
- `commands`: copy-paste shell commands for next steps

bv --robot-triage        # THE MEGA-COMMAND: start here
bv --robot-next          # Minimal: just the single top pick + claim command

#### Other Commands

**Planning:**
| Command | Returns |
|---------|---------|
| `--robot-plan` | Parallel execution tracks with `unblocks` lists |
| `--robot-priority` | Priority misalignment detection with confidence |

**Graph Analysis:**
| Command | Returns |
|---------|---------|
| `--robot-insights` | Full metrics: PageRank, betweenness, HITS (hubs/authorities), eigenvector, critical path, cycles, k-core, articulation points, slack |
| `--robot-label-health` | Per-label health: `health_level` (healthy\|warning\|critical), `velocity_score`, `staleness`, `blocked_count` |
| `--robot-label-flow` | Cross-label dependency: `flow_matrix`, `dependencies`, `bottleneck_labels` |
| `--robot-label-attention [--attention-limit=N]` | Attention-ranked labels by: (pagerank × staleness × block_impact) / velocity |

**History & Change Tracking:**
| Command | Returns |
|---------|---------|
| `--robot-history` | Bead-to-commit correlations: `stats`, `histories` (per-bead events/commits/milestones), `commit_index` |
| `--robot-diff --diff-since <ref>` | Changes since ref: new/closed/modified issues, cycles introduced/resolved |

**Other Commands:**
| Command | Returns |
|---------|---------|
| `--robot-burndown <sprint>` | Sprint burndown, scope changes, at-risk items |
| `--robot-forecast <id\|all>` | ETA predictions with dependency-aware scheduling |
| `--robot-alerts` | Stale issues, blocking cascades, priority mismatches |
| `--robot-suggest` | Hygiene: duplicates, missing deps, label suggestions, cycle breaks |
| `--robot-graph [--graph-format=json\|dot\|mermaid]` | Dependency graph export |
| `--export-graph <file.html>` | Self-contained interactive HTML visualization |

#### Scoping & Filtering

bv --robot-plan --label backend              # Scope to label's subgraph
bv --robot-insights --as-of HEAD~30          # Historical point-in-time
bv --recipe actionable --robot-plan          # Pre-filter: ready to work (no blockers)
bv --recipe high-impact --robot-triage       # Pre-filter: top PageRank scores
bv --robot-triage --robot-triage-by-track    # Group by parallel work streams
bv --robot-triage --robot-triage-by-label    # Group by domain

#### Understanding Robot Output

**All robot JSON includes:**
- `data_hash` — Fingerprint of source beads.jsonl (verify consistency across calls)
- `status` — Per-metric state: `computed|approx|timeout|skipped` + elapsed ms
- `as_of` / `as_of_commit` — Present when using `--as-of`; contains ref and resolved SHA

**Two-phase analysis:**
- **Phase 1 (instant):** degree, topo sort, density — always available immediately
- **Phase 2 (async, 500ms timeout):** PageRank, betweenness, HITS, eigenvector, cycles — check `status` flags

**For large graphs (>500 nodes):** Some metrics may be approximated or skipped. Always check `status`.

#### jq Quick Reference

bv --robot-triage | jq '.quick_ref'                        # At-a-glance summary
bv --robot-triage | jq '.recommendations[0]'               # Top recommendation
bv --robot-plan | jq '.plan.summary.highest_impact'        # Best unblock target
bv --robot-insights | jq '.status'                         # Check metric readiness
bv --robot-insights | jq '.Cycles'                         # Circular deps (must fix!)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'

**Performance:** Phase 1 instant, Phase 2 async (500ms timeout). Prefer `--robot-plan` over `--robot-insights` when speed matters. Results cached by data hash.

Use bv instead of parsing beads.jsonl—it computes PageRank, critical paths, cycles, and parallel tracks deterministically.
BV_DOCS

    info "bv documentation added to CLAUDE.md"
}

# Main execution
main() {
    echo "=========================================="
    echo "  Beads + Beads Viewer Setup Script"
    echo "=========================================="
    echo ""

    # Step 1: Install bd
    info "Step 1: Installing beads (bd)..."
    install_bd || { error "Failed to install bd"; exit 1; }
    echo ""

    # Step 2: Install bv
    info "Step 2: Installing beads_viewer (bv)..."
    install_bv || { error "Failed to install bv"; exit 1; }
    echo ""

    # Step 3: Initialize beads in project
    info "Step 3: Initializing beads in project..."
    init_beads || { error "Failed to initialize beads"; exit 1; }
    echo ""

    # Step 4: Setup CLAUDE.md
    info "Step 4: Setting up CLAUDE.md with bv documentation..."
    setup_claude_md || { error "Failed to setup CLAUDE.md"; exit 1; }
    echo ""

    echo "=========================================="
    echo "  Setup Complete!"
    echo "=========================================="
    echo ""
    info "Project directory: $PROJECT_DIR"
    info "Beads data: $PROJECT_DIR/.beads/"
    info "Claude docs: $PROJECT_DIR/CLAUDE.md"
    echo ""
    info "Quick start commands:"
    echo "  bd create 'My first issue'     # Create an issue"
    echo "  bd list                         # List all issues"
    echo "  bv --robot-triage              # AI-friendly triage (use this!)"
    echo "  bv                              # Interactive TUI (humans only)"
    echo ""
    warn "Remember: AI agents should ONLY use 'bv --robot-*' flags!"
}

main "$@"