beads
br is a personal, agent-friendly issue tracker: a single SQLite-backed binary with a JSONL export for portability and version control.
Install
This project is not published to crates.io. GitHub Releases is the only binary distribution channel. A downloaded release binary needs no C compiler and no system libsqlite3 to run, since SQLite is statically linked into every release artifact.
Each release carries four archives. Pick the one matching your platform, verify it against the published br<versionchecksums.txt, and put br somewhere on your PATH:
tar xzf br_1.0.0_aarch64-apple-darwin.tar.gz
install -m755 br ~/.local/bin/br
br --version| Platform | Archive | | --- | --- | | Linux, x8664 | br<versionx8664-unknown-linux-musl.tar.gz | | Linux, arm64 | br<versionaarch64-unknown-linux-musl.tar.gz | | macOS, Apple silicon | br<versionaarch64-apple-darwin.tar.gz | | macOS, Intel | br<versionx8664-apple-darwin.tar.gz |
The Linux downloads are musl builds and there is no glibc variant, by design: they link fully static, so they carry no GLIBC version requirement and the same binary runs on any distribution including Alpine.
There is no Windows binary — see docs/RELEASING.md for why, and for why Linux is musl-only.
To build from source instead:
git clone https://github.com/Toshik1978/beads
cd beads
cargo install --path .cargo install --path . needs a working C compiler on your machine: the rusqlite dependency's bundled feature compiles the SQLite amalgamation from source. This is the one requirement a release download does not have.
Rust 1.95 or newer is required (see rust-version in Cargo.toml). There is no rust-toolchain.toml; the project builds on any current stable toolchain.
Usage
br init # create a .beads/ workspace in the current directory
br create "Fix the bug" # create an issue
br ready # list issues that are open and unblocked
br listbr --help lists all 27 top-level commands. Full documentation for every command, its flags, exit codes, and --json output schemas lives in docs/CLIREFERENCE.md.
Storage
Each workspace is a .beads/ directory holding a SQLite database plus an issues.jsonl export. The JSONL file's serialized field set is a stable, tested interface (tests/storage/schemashape.rs) so that external tools built against it keep working across releases.