beads_viewer (bv): a graph-aware TUI on top of the Beads issue tracker
Graph-aware TUI for the Beads issue tracker: PageRank, critical path, kanban, dependency DAG visualization, and robot-mode JSON API
At a glance
- What is it?
- bv reads Beads JSONL exports and adds PageRank, critical path analysis, a dependency DAG view and a robot-mode JSON API. It is a viewer, not a tracker, and that boundary decides who should install it.
- Who is it for?
- Adopt bv if you already run Beads through br or bd and want dependency structure, PageRank ordering and critical path visible in a terminal without a server. Do not adopt it if you need a tracker with its own storage, a web UI, or a Windows environment where you cannot install a Nerd Font, since the README asks for one for best display.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap bv fills: Beads stores issues, it does not rank them
Beads is an issue tracker. What it does not appear to ship, based on this repository, is a way to look at the dependency graph those issues form and ask which node matters most. bv is that layer. The README describes it as a terminal interface for browsing and managing tasks in projects that use Beads, and the topics listed for the repository (graph-analysis, issue-tracker, tui) match the feature set: PageRank, critical path, cycles, a kanban board and a DAG view.
The intended user is someone already committed to Beads and working from a terminal. The README's own framing is local browsing of thousands of issues without a network. If your issues live somewhere else, bv has nothing to read. There is no importer for Jira, GitHub Issues or Linear in the material provided, and no server component. The tool is a consumer of one file format produced by one ecosystem.
That narrowness is the point. A tracker that already knows the dependency edges between issues can compute things a flat list cannot, and bv does that computation on the client side, reading a file rather than querying an API.
How bv gets its data: JSONL in .beads/, produced by br or bd
bv does not talk to a database. It reads Beads JSONL exports from `.beads/`. The README states that current `br` and Dolt-backed `bd` workspaces use `.beads/issues.jsonl`, while older legacy workspaces may use `.beads/beads.jsonl`, and that bv auto-discovers the supported file names.
That means there is an export step between your tracker and your viewer, and it is not optional. Rust users running `br` are told to run `br sync --flush-only` after Beads mutations so `.beads/issues.jsonl` is current. Go users running `bd` run `bd export -o .beads/issues.jsonl`. The README's claim that bv works identically regardless of which tool produced the file is plausible given that both paths converge on the same JSONL, but it also means bv inherits whatever staleness exists in that file. If you mutate issues and skip the flush or export, the graph you are looking at is the graph as of the last export.
This is the architecture in one sentence: bv is a read-side consumer of a file that another tool writes. Everything downstream (PageRank, critical path, kanban columns, the DAG view) is computed from that snapshot. There is no live connection to reconcile against.
Installation: Homebrew and Scoop first, direct archives with checksums second
The README lists Homebrew as the recommended path for macOS and Linux: `brew install dicklesworthstone/tap/bv`. On Windows, Scoop: `scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket` followed by `scoop install dicklesworthstone/bv`. Both package managers select the version from their own published manifests, so pinning a specific release means using a release archive instead.
Direct downloads follow the naming pattern `bv_<version>_<os>_<arch>.tar.gz`, with `.zip` on Windows. The README gives `bv_0.23.0_linux_amd64.tar.gz` and `bv_0.23.0_darwin_arm64.tar.gz` as examples and notes that the version is embedded in the filename so a downloaded file always says which release it came from. Each release also ships `checksums.txt`, and the documented verification is `sha256sum -c --ignore-missing checksums.txt`. Releases up to v0.22.0 used unversioned names, and both `bv --update` and `install.sh` accept either form.
The install script path deserves attention. The README explicitly warns that `curl ... | bash` runs whatever the URL serves at that moment, and recommends pinning to a reviewed commit instead of the moving `main` branch. It provides a specific commit hash for that purpose and states that `install.sh` verifies the archive against the release `checksums.txt` and refuses to install on a mismatch. The Windows PowerShell equivalent uses `Get-FileHash`, accepts `-Version` and `-InstallDir` (default `%LOCALAPPDATA%\Programs\bv`), and needs no Go toolchain. A source build via `install.ps1 -FromSource -Version v0.24.1` requires Git and Go 1.25 or later.
Robot mode is the part most teams will actually script against
The README carries an explicit warning: never run bare `bv` in an agent context, because it launches the interactive TUI. Everything scriptable goes through `--robot-*` flags. The entry point is `bv --robot-triage`, described as a single-call mega-command. A narrower option is `bv --robot-next`, which returns the top pick plus a claim command. `bv --robot-help` lists the rest.
The output contract is stated plainly: stdout carries JSON or TOON data only, stderr carries diagnostics, and exit 0 means success. That separation is what makes the tool usable from a shell pipeline or an agent loop without parsing mixed output.
The TOON path is where the README is unusually candid, and it is worth reading closely. TOON uses an external `toon_rust` encoder. Discovery honors `TOON_TRU_BIN` or `TOON_BIN`, then looks for `tru` or `toon` on PATH and the library's known fallback paths, validating candidates as `toon_rust`. If nothing qualifies, bv warns on stderr and emits JSON. The README states directly that a successful fallback is not evidence that TOON encoding ran, and that the format is smaller only for wide tabular payloads such as `--robot-graph`, while it is larger for nested ones such as `--robot-triage`. The documented way to check is `bv --robot-triage --format toon --stats` before adopting it. `BV_OUTPUT_FORMAT=toon` sets the default. The README also advises keeping the format at JSON when copying the jq examples.
Where bv is the wrong tool
The dependency on a pre-generated JSONL file is the sharpest limitation. bv has no write path to Beads that the README describes. It browses and manages tasks in the terminal, but the data it manages lives in a file that `br sync --flush-only` or `bd export -o .beads/issues.jsonl` produced. A team that wants one tool to both file an issue and rank it will not get that here, at least not from the documented surface.
Second, the README's own install guidance treats the script path as something to be cautious about. That is a reasonable posture, but it does mean the lowest-friction install is the one the maintainer tells you to pin to a commit you have read. Teams that cannot review a shell script before running it should stick to Homebrew, Scoop or a checksum-verified archive.
Third, the display requirements are non-trivial on Windows. The README asks for Windows Terminal with a Nerd Font for best display. That is a real setup cost on managed machines where font installation is restricted.
Finally, the licence is listed as NOASSERTION in the repository metadata while the README badge says MIT plus an OpenAI/Anthropic rider. Those two signals disagree, and the discrepancy is not something this article can resolve. Anyone embedding bv in a product, or redistributing a modified binary, should read the actual licence file rather than the badge. Nothing here is legal advice.
The alternative: a web-based tracker with server-side graph queries
The obvious comparison is a hosted or self-hosted issue tracker that stores its own data and exposes a query API. The difference in approach is where the work happens. A server-backed tracker computes relationships on the server, keeps state authoritative in a database, and lets multiple people read and write concurrently. bv inverts all three: the data is a local file, the graph math runs on your machine, and the README frames the value as browsing thousands of issues without a network.
That inversion has consequences in both directions. bv works on a plane, in an air-gapped environment, or against a repository you have checked out and never intend to push. It also means two engineers looking at bv at the same moment may be looking at two different exports, and neither is authoritative until the next flush. A server-backed tracker does not have that problem, and pays for it with a network dependency and a running service.
If your team's bottleneck is coordinating writes across people and systems, bv is not the answer. If your bottleneck is that you cannot see the shape of your own backlog, and the backlog already lives in Beads, bv addresses exactly that.
Release cadence, upgrade cost and what to check before adopting
The release history shows v0.23.0, v0.24.0 and v0.24.1 within roughly a week in early September 2026, with the last push to the repository shortly after. That cadence means the tool is moving, and it also means the install path matters more than usual. Homebrew and Scoop users get `brew upgrade` and the equivalent, but the README notes those managers select the version in their published manifests, so you may be a release or two behind what the repository has tagged. Pinning with `-Version v0.24.1` on the PowerShell installer, or downloading the matching archive, gives you a known point.
There is one upgrade caveat stated in the README that is easy to miss: selecting an older release tag does not include later, unreleased fixes from the checkout. If you pin an old tag to avoid churn, you are also opting out of fixes that landed after it.
Upgrade cost itself is low. bv is a single binary with no server, no database migration and no schema to reconcile. The data it reads is owned by br or bd, so a bv upgrade cannot corrupt your issues. The thing that can go stale is the JSONL file, and that staleness is a property of your workflow, not of the tool.
Before rolling it out, do three checks in your own environment. Confirm which file name bv discovers in your `.beads/` directory, since the README supports both `issues.jsonl` and the legacy `beads.jsonl`. Run your flush or export command and confirm the file's modification time actually moves. And if you plan to use TOON rather than JSON, run the `--stats` comparison the README describes, because the encoder can silently fall back to JSON and the output size advantage only holds for wide tabular payloads like `--robot-graph`.
Editorial conclusion
Adopt bv if you already run Beads through br or bd and want dependency structure, PageRank ordering and critical path visible in a terminal without a server. Do not adopt it if you need a tracker with its own storage, a web UI, or a Windows environment where you cannot install a Nerd Font, since the README asks for one for best display. Before committing, verify three things in your own workspace: that bv auto-discovers your JSONL file name, that a fresh export actually reflects your latest mutations, and that your TOON encoder, if you intend to use one, is a real toon_rust binary rather than a silent JSON fallback.
Community notes