session-viewer/AGENTS.md

Agent Instructions

Guidance for Claude Code and other AI agents working in this repository.

Development Principles

Find the simplest solution that meets all acceptance criteria. Use third party libraries whenever there's a well-maintained, active, and widely adopted solution (for example, date-fns for TS date math) Build extensible pieces of logic that can easily be integrated with other pieces. DRY principles should be loosely held. Architecture MUST be clear and well thought-out. Ask the user for clarification whenever ambiguity is discovered around architecture, or you think a better approach than planned exists.

---

Issue Tracking with br (beads_rust)

All issue tracking goes through br (beads_rust). No other TODO systems.

Key invariants:

• .beads/ is authoritative state and must always be committed with code changes.
• Do not edit .beads/*.jsonl directly; only via br.
• br is non-invasive: it NEVER executes git commands. You must manually commit .beads/ changes.

Basics

Check ready work:

br ready --json

Create issues:

br create "Issue title" -t bug|feature|task -p 0-4 --json
br create "Issue title" -p 1 --deps discovered-from:bv-123 --json

Update:

br update bv-42 --status in_progress --json
br update bv-42 --priority 1 --json

Complete:

br close bv-42 --reason "Completed" --json

Types:

• bug, feature, task, epic, chore

Priorities:

• 0 critical (security, data loss, broken builds)
• 1 high
• 2 medium (default)
• 3 low
• 4 backlog

Agent workflow:

1. br ready to find unblocked work.
2. Claim: br update <id> --status in_progress.
3. Implement + test.
4. If you discover new work, create a new bead with discovered-from:<parent-id>.
5. Close when done.
6. Sync and commit:

   br sync --flush-only    # Export to JSONL (no git ops)
   git add .beads/         # Stage beads changes
   git commit -m "..."     # Commit with code changes
   

Never:

• Use markdown TODO lists.
• Use other trackers.
• Duplicate tracking.

---

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 multi-agent coordination (messaging, work claiming, file reservations), see the optional MCP Agent Mail section above.

⚠️ 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, 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 --profile-startup for diagnostics.

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

---

Hybrid Semantic Search (CLI)

bv --search supports hybrid ranking (text + graph metrics).

# Default (text-only)
bv --search "login oauth"

# Hybrid mode with preset
bv --search "login oauth" --search-mode hybrid --search-preset impact-first

# Hybrid with custom weights
bv --search "login oauth" --search-mode hybrid \
  --search-weights '{"text":0.4,"pagerank":0.2,"status":0.15,"impact":0.1,"priority":0.1,"recency":0.05}'

# Robot JSON output (adds mode/preset/weights + component_scores for hybrid)
bv --search "login oauth" --search-mode hybrid --robot-search

Env defaults:

• BV_SEARCH_MODE (text|hybrid)
• BV_SEARCH_PRESET (default|bug-hunting|sprint-planning|impact-first|text-only)
• BV_SEARCH_WEIGHTS (JSON string, overrides preset)

---

Static Site Export for Stakeholder Reporting

Generate a static dashboard for non-technical stakeholders:

# Interactive wizard (recommended)
bv --pages

# Or export locally
bv --export-pages ./dashboard --pages-title "Sprint 42 Status"

The output is a self-contained HTML/JS bundle that:

• Shows triage recommendations (from --robot-triage)
• Visualizes dependencies
• Supports full-text search (FTS5)
• Works offline after initial load
• Requires no installation to view

Deployment options:

• bv --pages → Interactive wizard for GitHub Pages deployment
• bv --export-pages ./dir → Local export for custom hosting
• bv --preview-pages ./dir → Preview bundle locally

For CI/CD integration:

bv --export-pages ./bv-pages --pages-title "Nightly Build"
# Then deploy ./bv-pages to your hosting of choice

---

ast-grep vs ripgrep

Use ast-grep when structure matters. It parses code and matches AST nodes, so results ignore comments/strings, understand syntax, and can safely rewrite code.

• Refactors/codemods: rename APIs, change patterns
• Policy checks: enforce patterns across a repo

Use ripgrep when text is enough. Fastest way to grep literals/regex.

• Recon: find strings, TODOs, config values
• Pre-filter: narrow candidates before precise pass

Go-specific examples:

# Find all error returns without wrapping
ast-grep run -l Go -p 'return err'

# Find all fmt.Println (should use structured logging)
ast-grep run -l Go -p 'fmt.Println($$$)'

# Quick grep for a function name
rg -n 'func.*LoadConfig' -t go

# Combine: find files then match precisely
rg -l -t go 'sync.Mutex' | xargs ast-grep run -l Go -p 'mu.Lock()'

---

Morph Warp Grep — AI-Powered Code Search

Use mcp__morph-mcp__warp_grep for exploratory "how does X work?" questions. An AI search agent automatically expands your query into multiple search patterns, greps the codebase, reads relevant files, and returns precise line ranges.

Use ripgrep for targeted searches. When you know exactly what you're looking for.

Scenario	Tool
"How is graph analysis implemented?"	warp_grep
"Where is PageRank computed?"	warp_grep
"Find all uses of NewAnalyzer"	ripgrep
"Rename function across codebase"	ast-grep

warp_grep usage:

mcp__morph-mcp__warp_grep(
  repoPath: "/path/to/beads_viewer",
  query: "How does the correlation package detect orphan commits?"
)

Anti-patterns:

• ❌ Using warp_grep to find a known function name → use ripgrep
• ❌ Using ripgrep to understand architecture → use warp_grep

---

UBS Quick Reference

UBS = "Ultimate Bug Scanner" — static analysis for catching bugs early.

Golden Rule: ubs <changed-files> before every commit. Exit 0 = safe. Exit >0 = fix & re-run.

ubs file.go file2.go                    # Specific files (< 1s)
ubs $(git diff --name-only --cached)    # Staged files
ubs --only=go pkg/                      # Go files only
ubs .                                   # Whole project

Output Format:

⚠️  Category (N errors)
    file.go:42:5 – Issue description
    💡 Suggested fix
Exit code: 1

Fix Workflow:

1. Read finding → understand the issue
2. Navigate file:line:col → view context
3. Verify real issue (not false positive)
4. Fix root cause
5. Re-run ubs <file> → exit 0
6. Commit

Bug Severity (Go-specific):

• Critical: nil dereference, division by zero, race conditions, resource leaks
• Important: error handling, type assertions without check
• Contextual: TODO/FIXME, unused variables

---

cass — Cross-Agent Session Search

cass indexes prior agent conversations (Claude Code, Codex, Cursor, Gemini, ChatGPT, Aider, etc.) into a unified, searchable index so you can reuse solved problems.

NEVER run bare cass — it launches an interactive TUI. Always use --robot or --json.

Quick Start

# Check if index is healthy (exit 0=ok, 1=run index first)
cass health

# Search across all agent histories
cass search "authentication error" --robot --limit 5

# View a specific result (from search output)
cass view /path/to/session.jsonl -n 42 --json

# Expand context around a line
cass expand /path/to/session.jsonl -n 42 -C 3 --json

# Learn the full API
cass capabilities --json      # Feature discovery
cass robot-docs guide         # LLM-optimized docs

Key Flags

Flag	Purpose
--robot / --json	Machine-readable JSON output (required!)
--fields minimal	Reduce payload: source_path, line_number, agent only
--limit N	Cap result count
--agent NAME	Filter to specific agent (claude, codex, cursor, etc.)
--days N	Limit to recent N days

stdout = data only, stderr = diagnostics. Exit 0 = success.

Robot Mode Etiquette

• Prefer cass --robot-help and cass robot-docs <topic> for machine-first docs
• The CLI is forgiving: globals placed before/after subcommand are auto-normalized
• If parsing fails, follow the actionable errors with examples
• Use --color=never in non-TTY automation for ANSI-free output

Pre-Flight Health Check

cass health --json

Returns in <50ms:

• Exit 0: Healthy—proceed with queries
• Exit 1: Unhealthy—run cass index --full first

Exit Codes

Code	Meaning	Retryable
0	Success	N/A
1	Health check failed	Yes—run cass index --full
2	Usage/parsing error	No—fix syntax
3	Index/DB missing	Yes—run cass index --full

Treat cass as a way to avoid re-solving problems other agents already handled.