br (beads_rust): a local-first issue tracker that freezes classic beads in Rust

The problem br targets: issue tracking that never leaves the repository

The README frames the problem in three parts. Hosted trackers such as GitHub or GitLab Issues need a network connection, pull context away from the code, and do not work offline. TODO comments survive offline but carry no status and cannot express dependencies. Paid tools such as Jira or Linear add context switching and a bill. br is aimed at people who want the first category's structure without the first category's location.

The intended user is not a project manager. It is a developer, or a swarm of coding agents, working inside a repository where the issue list is a file next to the source. The README describes the command as br, deliberately different from the original bd, so both binaries can coexist. The author states that the project exists to freeze the classic SQLite plus JSONL architecture his Agent Flywheel tooling was built around, after upstream beads moved toward GasTown. That is a narrow and honest motivation: this is a snapshot for one workflow, not a general-purpose tracker trying to win a comparison table.

SQLite for queries, JSONL for git: how the two stores divide the work

The architecture is a hybrid. A SQLite database under .beads/ answers local queries quickly, and a JSONL file under the same directory is the collaboration artifact. The README shows the directory holding beads.db, issues.jsonl and an optional config.yaml.

The data flow is one-directional in normal use: a successful mutating command writes SQLite and then flushes JSONL by default. The README calls this explicit over implicit and notes that br sync --flush-only is an idempotent final export check rather than a required step. For collaboration, the JSONL file is what you stage and commit, and the README shows a git diff of .beads/issues.jsonl producing a single added JSON object per issue. That is the whole reason for JSONL over a binary database: line-oriented merges behave better in git than a database file.

A detail worth noticing is the storage engine. Cargo.toml declares fsqlite, described in a comment as a pure-Rust SQLite with concurrent writer support, and states that br never links a C SQLite. The dependency list pins fsqlite 0.4.0 with features including fts5, rtree and icu. For a tool whose whole job is a local database, choosing a Rust reimplementation of SQLite over the C library is a meaningful decision: it removes a C toolchain dependency, and it also means you are trusting an engine that is not the one everybody else runs.

Installing br and running a first dependency-aware workflow

The README gives a single install command that detects the platform and downloads a binary, covering Linux, macOS and Windows under WSL. The query string is there to defeat caching.

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)" | bash

The README documents two install flags: --skip-skills skips the Claude Code and Codex skills, and --with-migration-skill also installs a bd-to-br migration skill, which is skipped by default and only needed when moving off classic bd. If you do not want the installer touching agent instruction files, --skip-skills is the flag to reach for.

After installing, initialize inside a repository and create two issues. Priorities run from 0 for critical to 4 for backlog.

cd my-project
br init
br create "Implement user auth" --type feature --priority 1
br create "Set up database schema" --type task --priority 1

The README shows the create command printing an identifier such as br-7f3a2c. Use those identifiers to declare that auth depends on the schema, then ask what is actually actionable.

br dep add br-7f3a2c br-e9b1d4
br ready

What you should see is only the schema task in the ready list, with the auth issue hidden because it is blocked. Closing the schema task with br close br-e9b1d4 --reason "Schema implemented" should make the auth issue appear the next time you run br ready. That round trip is the core of the tool, and it is the first thing worth verifying in your own repository.

What br will not do, and where the design gets in your way

The README is unusually direct about the boundary. For normal issue tracking and sync, br keeps state in .beads/ and leaves the git handoff to you. It does not commit, push, pull, install hooks or run as a background service. If you expected the tracker to keep a remote in sync, it will not, and the README says so before you install it.

That non-invasive default has named exceptions, and they matter when you are deciding whether this tool respects your tree. The README lists commands that deliberately step outside the storage boundary: br agents edits agent instruction files, br doctor --repair can modify the project .gitignore, br config edit and br config set write config files, br completions -o writes shell completion files, br upgrade replaces the installed binary, and the git-reporting commands br changelog, br orphans, commit-activity br stats and the bounded br vcs-status diagnostic read git state and history. None of those are surprising once listed, but a tool that advertises itself as non-invasive should be read with that list in hand.

The larger limitation is architectural and the README states it plainly: this is a frozen snapshot. Upstream beads is evolving toward GasTown, and this port deliberately does not follow. You get stability at the cost of divergence. Anything upstream adds that depends on the new architecture will not arrive here, and the maintenance burden sits with one author and his tooling. There is also no homepage listed for the repository, so the README and the repository itself are the documentation.

br against Linear and against plain TODO comments

The README's own comparison table sets br beside GitHub Issues, Jira and TODO comments on offline operation, whether the data lives in the repository, dependency tracking, cost, account requirements, machine-readable output and git-friendly sync. The useful comparison is not the table's checkmarks but the shape of each alternative.

Linear is a hosted product. Its model is a shared, always-current board with a web interface, and its value comes from being the same view for everyone on a team regardless of which repository they have checked out. br inverts that: the source of truth is a file in your working copy, and two people see the same state only after a git merge. If your team needs a board that a designer or a manager can open without cloning anything, br is the wrong tool and no amount of --json output changes that.

Plain TODO comments are the opposite failure. They are already in the file, they already work offline, and they cost nothing, which is exactly why they accumulate without status, ownership or ordering. br adds the missing structure: a status, a priority, an assignee, and a dependency edge that makes br ready answer a question TODO comments cannot. The trade is that issues now live in a second place, .beads/, and the code comment no longer carries the whole story. The README also points at a companion project, beads_viewer, described as adding an analysis layer over beads, which is the direction to look if the CLI output is not enough.

Maintenance, upgrades and what the licence actually says

The repository is not archived and the last push was on 2026-09-10, with v0.5.12 released on 2026-09-09 and two releases in the preceding week. Cargo.toml declares version 0.6.0 while the newest published release is v0.5.12, so the working tree is ahead of the last tagged release. A CHANGELOG.md and an UPGRADE_LOG.md are present at the top level, and the README documents br upgrade as the command that updates the installed binary.

The licence needs care. The GitHub metadata reports NOASSERTION, and Cargo.toml uses license-file = "LICENSE" rather than an SPDX identifier. The README badge says MIT plus an OpenAI/Anthropic rider. That rider is the part to read in full before you depend on the code, because a rider attached to MIT is not the same grant as plain MIT, and the repository metadata does not classify it. This is a description of what the files say, not legal advice; if the terms matter to your organisation, read LICENSE directly.

Upgrade cost is low in the ordinary case because the binary is self-contained and state lives in .beads/. The risk sits in the frozen architecture: if you later want features that only exist in upstream beads, the README's own framing suggests you would be migrating rather than upgrading, and the installer's optional --with-migration-skill flag covers the opposite direction, moving from classic bd to br.

Editorial conclusion

Adopt br if you work in a git repository, want issues under .beads/ and machine-readable output for scripts or coding agents, and are comfortable with a CLI. Do not adopt it if you need a hosted board, a graphical interface, or a tracker that is not tied to a working copy. Before committing, run br init in a scratch repository, create two issues, link them with br dep add, and confirm that br ready hides the blocked one and that .beads/issues.jsonl changes after the mutation, since that file is what your collaborators will merge.

Frequently asked questions

Official sources

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