beads_viewer

led comments so that the whole thing is totally self-contained and self-documenting (including relevant background, reasoning/justification, considerations, etc.-- anything we'd want our "future self" to know about the goals and intentions and thought process and how it serves the overarching goals of the project.)" Anyway, I wished I had a better way to just browse the beads and see what's going on with them. And sure, I get it, beads aren't for me as a human, they're for the agents. But I'm using them so much that it would be helpful for me to also have a way to interact and view and browse them. Plus I had an idea that there was additional useful information lurking in the "graph" of beads of a sufficiently complex project comprising enough beads across various epics with lots of dependency structure on top. So I started making beads_viewer (bv for short), and I'm pleased to say that it's already pretty amazingly polished, full-featured, and useful. All written in highly performant Golang (a language I only started using again recently, with the system monitor program I also released this morning). You run the one-liner curl bash installer (see the README in the repo linked below) and then you can go into any project folder where you're using beads and simply type bv to open it. The interface is pretty straightforward; press F1 to see the available commands. Try pressing the "i" key for insights, "g" for graph, "b" for a kanban board, "/" for a fuzzy search across beads in the main view, etc. I do some cool graph theoretic calculations on the beads graph structure to extract some interesting insights. And as a tool for use with beads, I'd be remiss if I didn't make sure that my AI robot brethren also enjoyed using it, so I added a mode just for them that is easy and useful for them. To get your agents to use it, simply drop this blurb into your AGENTS dot md or CLAUDE dot md file: ``` ### Using bv as an AI sidecar bv is a fast terminal UI for Beads projects (.beads/beads.jsonl). It renders lists/details and precomputes dependency metrics (PageRank, critical path, cycles, etc.) so you instantly see blockers and execution order. For agents, it’s a graph sidecar: instead of parsing JSONL or risking hallucinated traversal, call the robot flags to get deterministic, dependency-aware outputs. - bv --robot-help — shows all AI-facing commands. - bv --robot-insights — JSON graph metrics (PageRank, betweenness, HITS, critical path, cycles) with top-N summaries for quick triage. - bv --robot-plan — JSON execution plan: parallel tracks, items per track, and unblocks lists showing what each item frees up. - bv --robot-priority — JSON priority recommendations with reasoning and confidence. - bv --robot-recipes — list recipes (default, actionable, blocked, etc.); apply via bv --recipe <name> to pre-filter/sort before other flags. - bv --robot-diff --diff-since <commit|date> — JSON diff of issue changes, new/closed items, and cycles introduced/resolved. ```

use but might in the future (like opencode, aider, and others). So I made cass in super high-performance rust with every optimization I could think of, and a huge amount of attention to ergonomics and user experience. I’m very pleased with how it came out and think you will be, too. But just as my recent bv ( https://github.com/Dicklesworthstone/beads_viewer ) tool is now being used way more by my agents than by me, I knew from the start that cass should have a “robot mode” designed specifically for use by coding agents. This tool gives coding agents the ability to reach into their own working notes and those of all their peer agents across tools. It’s like a human developer being able to search their Gmail, their notes, and their company Slack and Jira to find things. I went through countless iterations of improving the tool so that agents really love to use it. You can just add this blurb to your AGENTS dot md file to get them to use it (after doing the one-liner curl install, which takes 3 seconds): ``` cass — Search All Your Agent History What: cass indexes conversations from Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, and more into a unified, searchable index. Before solving a problem from scratch, check if any agent already solved something similar. 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 Why Use It - Cross-agent knowledge: Find solutions from Codex when using Claude, or vice versa - Forgiving syntax: Typos and wrong flags are auto-corrected with teaching notes - Token-efficient: --fields minimal returns only essential data 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. ```