Toshik1978/beads-viewer

bv

br is a command-line issue tracker that stores a project's issues as .beads/issues.jsonl. bv is its read-only terminal companion: it reads that file and gives you four ways to look at it — a list with a detail pane, a parent/child tree, a kanban board, and a dependency board showing what blocks the issue you are on and what is waiting on it — with live reload as br writes.

bv never writes anywhere inside .beads/ and never spawns a subprocess. br is the only thing that ever changes your data; bv only reads it.

Install

Release archive

Each release publishes four archives, one per platform:

| Platform | Archive | |---|---| | Linux, x8664 | bv<versionlinuxamd64.tar.gz | | Linux, arm64 | bv<versionlinuxarm64.tar.gz | | macOS, Intel | bv<versiondarwinamd64.tar.gz | | macOS, Apple silicon | bv<versiondarwinarm64.tar.gz |

There is no Windows build. Download the archive for your platform and its checksum, verify, then extract:

sha256sum -c bv_<version>_checksums.txt --ignore-missing   # Linux
shasum -a 256 -c bv_<version>_checksums.txt --ignore-missing   # macOS: sha256sum isn't stock
tar xzf bv_<version>_<os>_<arch>.tar.gz

Each archive contains the bv binary alongside LICENSE and this README.md. MIT requires the copyright notice to travel with every copy, so LICENSE ships inside the archive rather than only in the repository.

From source

go install github.com/Toshik1978/beads-viewer/cmd/bv@latest

This requires a Go toolchain (go.mod currently targets Go 1.27) and builds with CGOENABLED=0.

Usage

Run bv from inside a project that has a .beads directory, or point it at one directly:

bv                    # discovers .beads/ by walking up from the working directory
bv --db path/to/.beads

Workspace discovery, in order: --db, then the BEADSDIR environment variable, then the nearest .beads directory at or above the current directory.

bv needs a terminal on stdin, and says so rather than starting when it does not have one — echo | bv, bv < /dev/null, or a cron job — so a redirected run ends in one line on stderr instead of a process that never returns. --version and --help are unaffected and pipe normally.