bv: a graph-aware TUI for the Beads issue tracker

What bv solves, and for whom

Beads is a local, file-backed issue tracker. Once a project has a few hundred issues with blocking relationships between them, the flat list stops being useful: the question is no longer "what is open" but "what unblocks the most other work". bv is a terminal interface that answers the second question. The README describes it as the keyboard-driven terminal interface for Beads, and the screenshots split into four views: a list plus detail pane, a kanban board on `b`, an insights panel, and a graph view on `g` for the dependency DAG.

The audience is narrow and specific. You need Beads already in use, a terminal you are happy living in, and enough issues that ranking matters. The README's own pitch is local browsing of thousands of issues without a network. That is the whole value proposition: no server, no sync, no account. If you are looking for a Beads UI that other people on a team can open in a browser, this is not it, and the repository does not claim otherwise.

How bv reads Beads data: JSONL in, graph out

bv does not talk to a Beads daemon. It reads a JSONL export from `.beads/`. Current `br` and Dolt-backed `bd` workspaces write `.beads/issues.jsonl`; older legacy workspaces may use `.beads/beads.jsonl`, and the README states that bv auto-discovers the supported file names. Once the file exists, the tool behaves the same regardless of which producer wrote it, which is the cleanest part of the design: the file is the interface.

The graph work happens on top of that parsed set. The Insights view exposes PageRank, critical path and cycle detection, and the dependencies in go.mod point at gonum for the graph maths and modernc.org/sqlite for SQLite-backed storage, with the Makefile enabling FTS5 for full-text search. The Makefile sets `CGO_CFLAGS := -DSQLITE_ENABLE_FTS5` for local builds, which tells you search is a build-time property rather than something toggled at runtime.

For agents there is a separate surface. The README warns never to run bare `bv` in an agent context because it launches the interactive TUI, and instead points at `--robot-*` flags. Output conventions are stated plainly: stdout carries JSON or TOON data only, stderr carries diagnostics, exit 0 means success. TOON is optional and depends on an external `toon_rust` encoder discovered via `TOON_TRU_BIN` or `TOON_BIN`, then `tru` or `toon` on PATH; if none is found, bv warns on stderr and emits JSON. The README is honest that a successful fallback is not evidence TOON ran, and that TOON is smaller only for wide tabular payloads such as `--robot-graph` while being larger for nested ones like `--robot-triage`. That is an unusually candid note in a README and worth taking at face value.

Installing bv and running a first triage

Homebrew is the recommended path on macOS and Linux. The README gives this command and notes that it brings automatic updates through `brew upgrade` and easy removal through `brew uninstall`.

brew install dicklesworthstone/tap/bv

Windows users go through Scoop instead, adding the bucket and then installing the package.

scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket
scoop install dicklesworthstone/bv

Both package managers install whichever version their published manifest selects. To pin a specific release, the README points at the release archives, named `bv_<version>_<os>_<arch>.tar.gz` (`.zip` on Windows), with a `checksums.txt` alongside. Verify before extracting:

sha256sum -c --ignore-missing checksums.txt

The install script exists but the README discourages piping it from a moving branch; it recommends pinning to a reviewed commit, and notes that the script verifies the archive against the release checksums and refuses to install on a mismatch. For a source build, the Makefile targets are `go build -o bv ./cmd/bv` and `go install ./cmd/bv`, and go.mod requires Go 1.26.0 with toolchain go1.26.8.

Now the first real use. Generate the export, because bv reads nothing until that file exists. The README gives the Go-side command:

bd export -o .beads/issues.jsonl

Rust-side `br` users run `br sync --flush-only` after Beads mutations instead. With the file in place, launch the TUI and press `g` for the graph or `b` for kanban. If you are driving this from an agent rather than a person, skip the TUI entirely:

bv --robot-triage

The README calls this a single-call mega-command and suggests starting with it. `bv --robot-next` is the minimal variant, returning just the top pick and a claim command. Expect JSON on stdout and nothing else; diagnostics go to stderr. `bv --robot-help` lists the rest.

Where bv breaks down

The JSONL dependency is the sharpest limitation. bv has no view of the tracker that is fresher than the file on disk, so a stale export produces confident, wrong rankings. Nothing documented suggests bv detects staleness or warns about it. If you mutate issues and forget to re-export, the critical path you are reading describes a project state that no longer exists.

There is a second, subtler failure mode in the agent path. The README explicitly warns that a successful TOON fallback is not evidence TOON encoding ran. An agent that assumes it received TOON when it actually received JSON will parse the wrong thing or fail in a way that looks like a data problem rather than a configuration one. If you adopt TOON, verify the encoder is discoverable before trusting the format flag, and note that the README itself suggests checking with `--stats` before adopting it for a given payload shape.

Finally, bv is the wrong tool if your team needs shared state. There is no server component, no multi-user story, no web interface documented. It is a single-user terminal program over a local file, and that is a design decision, not a gap waiting to be filled.

How bv differs from the Beads CLI and from a hosted board

The obvious alternative is the Beads command line itself. `bd` and `br` are the tools that create and mutate issues; bv is a reader that ranks what they produced. The difference is not cosmetic. A CLI answers queries you already know how to phrase. bv computes PageRank and critical path over the dependency graph and puts the result in front of you, then lets you move through it with keystrokes. If you have never wanted to know which issue blocks the most downstream work, the CLI is enough and bv adds a build step for nothing.

The other alternative class is a hosted issue board with a web UI. Those give you multi-user assignment, notifications and remote access. They also require a server, and they generally do not compute a dependency ranking at all: the board shows columns, not graph centrality. Choosing between them is choosing between a shared surface and an analytical one. bv is firmly the second, and the `--robot-*` flags extend that analysis to agents rather than to teammates.

Maintenance, upgrades and the licence question

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent: v0.23.0 on 2026-09-04, v0.24.0 on 2026-09-07, v0.24.1 on 2026-09-08. The presence of `.goreleaser.yaml`, a `scripts/release_gate.sh` driven through Make targets, a `CHANGELOG.md` and an `UPGRADE_LOG.md` in the top-level tree indicates a release process with gates rather than ad hoc tagging. The Makefile separates `release-gate`, `release-package`, `release-verify` and `release-audit`, and the audit target runs `govulncheck` outside the module requirements, which is a sensible split.

Upgrade cost is low on the package-manager path: `brew upgrade` or the Scoop equivalent. Direct-download users should re-verify against `checksums.txt` each time. Source builders need Go 1.26.0 or newer and should expect the vendored dependency tree to move with each tag; the README notes that selecting an older release tag does not include later unreleased fixes from the checkout.

The licence is the part to read carefully. The repository metadata reports NOASSERTION, while the README badge says `MIT+OpenAI/Anthropic Rider`. Those are not the same statement, and the rider is not a standard OSI licence. Whether the additional terms affect your use depends on your situation, so read the LICENSE file rather than the badge. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt bv if your work already lives in Beads and the dependency graph, not the ticket list, is what you keep getting wrong: the Insights panel and the robot commands are built for exactly that. Skip it if you want a hosted board, multi-user assignment or anything that reads a live remote tracker, because bv only ever sees the JSONL export you generate. Before trusting the numbers, export with bd export -o .beads/issues.jsonl or br sync --flush-only, then run bv --robot-triage and check that the top pick matches a blocker you already know about; if the export is stale, every ranking in the UI is stale with it.

Frequently asked questions

Official sources

1. Dicklesworthstone/beads_viewer on GitHub
2. Issues
3. README
4. Releases