br (beads_rust): a frozen SQLite plus JSONL issue tracker for git repositories

The gap br fills: issues that live where the code lives

The README states the problem directly. GitHub and GitLab Issues require internet access, fragment context away from the code, and do not work offline. TODO comments get lost, carry no status, and cannot express dependencies. Jira and Linear add context switching and cost money. br takes a fourth position: a local-first tracker whose state sits in a .beads/ directory inside the repository, with SQLite for queries and a JSONL file for git collaboration. The intended user is a developer or an agent-driven workflow that already treats the repository as the source of truth. The README's own framing is a Rust port of Steve Yegge's beads, frozen at the classic SQLite plus JSONL architecture, with the command named br to distinguish it from the original bd. The author states plainly that upstream beads is moving toward a different design (GasTown) and that this port exists to hold the older architecture still. That is an unusual reason to fork, and it is the most important thing to understand before adopting: br's value proposition is partly stability rather than novelty.

Storage model: SQLite for speed, JSONL for git

Two files carry the state. According to the README, .beads/ contains beads.db (the SQLite database), issues.jsonl (the git-friendly export), and an optional config.yaml. Reads go to SQLite, which is what makes queries like br list --priority 0-1 --status open --assignee alice practical on a laptop. Collaboration goes through the JSONL file, which is line-oriented and therefore diffs and merges at the record level rather than the file level. The README shows the shape of a diff: a single added line beginning with a JSON object containing id, title and the remaining fields. That is the whole architecture, and it is worth being precise about the consequence. SQLite is a binary file and a poor fit for git, so it is the JSONL export that gets committed. The export is flushed automatically after successful mutating commands by default, and br sync --flush-only is described as an idempotent final export check to run before a git commit. The phrase idempotent matters here: running it twice should not change the file, which makes it safe to script. What the README does not document in the material available is the conflict resolution policy when two branches edit the same issue record. JSONL merges cleanly when records are disjoint, but a genuine field-level conflict on the same issue is still a conflict, and the documentation does not say how br detects or reports one.

Dependencies and the ready queue

The feature that separates br from a text file of TODOs is dependency tracking. The README's worked example creates two issues, then runs br dep add br-7f3a2c br-e9b1d4 to declare that the auth feature depends on the database schema task. After that, br ready prints only the issues that are not blocked, so the schema task appears and the auth feature does not. Closing the schema task with br close br-e9b1d4 --reason "Schema implemented" makes the auth feature appear in the next br ready output. Priority is a separate axis, set at creation with --priority and described in the README as 0 for critical through 4 for backlog. The output of br ready is columnar and compact: identifier, priority, type, title. This is the mechanism an agent loop would consume, and it is also why the machine-readable flag matters. The README lists --json as a general capability and shows br coordination status --json as an example. The coordination subcommand is described as inspecting hidden in-progress claims, which suggests br tracks who or what has claimed an issue separately from its status field. The material does not explain the claim model further, so treat that as something to verify by reading the help output rather than assuming.

Getting it running: install script, init, and the first commands

The README gives a curl piped to bash install line that fetches install.sh from the main branch with a cache-busting timestamp query parameter. The script is stated to work on Linux, macOS, and Windows under WSL, detecting the platform and downloading the matching binary. Two flags are documented: --skip-skills skips the Claude Code and Codex skill files, and --with-migration-skill additionally installs a bd-to-br-migration skill that is skipped by default and only needed when moving off classic bd. Note that piping a remote script to bash runs whatever the branch currently contains; if that concerns you, download install.sh, read it, and run it locally. Once installed, the sequence is br init inside the repository, then br create with a title and optional --type and --priority flags, then br dep add to wire dependencies, br ready to see unblocked work, br update to change status, and br close to finish. br agents --add --force writes agent instructions into AGENTS.md, creating the file if it does not exist. Configuration lives in .beads/config.yaml, and br config edit and br config set are the documented ways to change it. The README does not enumerate the available config keys, so plan on inspecting the generated file or the command help.

The non-invasive claim has a documented list of exceptions

The README's first design principle is that br keeps state in .beads/ and leaves git handoff to you: it does not commit, push, pull, install hooks, or run as a background service. That is a real constraint and it shapes how the tool fits into a workflow. It also means br will not save you from forgetting to commit the JSONL. The README then lists the 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 a bounded br vcs-status diagnostic) read git state and history. Read that list as the actual security and surprise surface. A tool that edits .gitignore on request is not the same as a tool that edits it silently, but the distinction only holds if you know which command does what. This is the section of the README most worth reading twice before running br doctor --repair on a repository you care about.

Where br is the wrong tool

Three cases stand out. First, any team that needs a shared, always-on view of work. br stores state in a git repository, so two people see the same issues only after a fetch and merge, and there is no server, no web UI, and no notification. Second, anything requiring per-user access control. The README's comparison table lists no account requirement as an advantage, and it is one, but the same property means there is no permission model: whoever can clone the repository can read and rewrite every issue. Third, repositories where .beads/issues.jsonl will be edited by many branches at once. The README sells JSONL as merging cleanly, and for disjoint records it does, but the material provides no description of conflict detection or repair for the same record. If your workflow produces long-lived branches that each touch the same handful of issues, expect manual merges. There is also a portability cost worth naming: the README documents the install script for Linux, macOS, and Windows under WSL, which is not the same as native Windows support. And the project requires a nightly Rust toolchain according to its own badge, which matters if you intend to build from source rather than use the prebuilt binary.

How it differs from the upstream beads project

The obvious alternative is not Jira or GitHub Issues. It is Steve Yegge's original beads, the project br ports. The README is explicit that the two have diverged by design: upstream is evolving toward GasTown and away from the hybrid SQLite plus JSONL architecture, while br freezes that architecture because the author's Agent Flywheel tooling was built against it. So the choice is not which tracker is better in the abstract. It is whether you want the moving target or the snapshot. Choosing upstream means following an actively changing design and whatever migration work that implies. Choosing br means the storage format and command surface are intended to stay put, at the cost of not receiving upstream's newer ideas. The README states that Steve Yegge has endorsed the port, which removes the awkwardness of a fork competing with its origin, but it does not change the underlying trade. A second, smaller alternative is the one the README implicitly dismisses: plain TODO comments in source. Those are genuinely non-invasive and need no install, but they cannot express a dependency graph or a status field, which is exactly the gap br targets.

Licence, maintenance, and what to check first

The repository metadata reports the licence as NOASSERTION, while the README carries a badge reading MIT plus an OpenAI and Anthropic rider, linking to a LICENSE file. Those two signals do not agree, and the rider is the part that would need reading in full before use in a commercial setting. I am not giving legal advice; the point is that the machine-readable licence field is not a substitute for the file. On maintenance, the release history shown here is dense: v0.5.10, v0.5.11 and v0.5.12 all landed within roughly a week in early September 2026, and the last push to the default branch is dated 2026-09-10. Frequent point releases at 0.x suggest an actively changing command surface, which sits in mild tension with the project's stated goal of being a stable snapshot. That is not a contradiction, since the frozen part is the architecture rather than the CLI, but it does mean upgrade cost is real: br upgrade replaces the installed binary, and any script depending on exact output formatting should be re-checked after each version bump. The install script's --with-migration-skill flag exists specifically because moving between bd and br is a distinct operation, so if you are coming from classic beads, that path is at least acknowledged in the tooling.

Editorial conclusion

Adopt br if your issue list belongs next to the code, your tooling reads JSON, and you accept that merge conflicts in .beads/issues.jsonl are yours to resolve. Do not adopt it if you need a hosted board, per-user permissions, or a web UI, because none of those exist here. Before committing, run br init in a scratch repository, create two issues, add a dependency with br dep add, and inspect the resulting .beads/issues.jsonl to confirm the on-disk format matches what your scripts expect. Then read the LICENSE file in full, since the repository metadata reports NOASSERTION while the README badge says MIT plus an OpenAI and Anthropic rider, and only you can decide whether those terms fit your organisation.

Official sources

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