Beads Task Tracker (`br`)

br (beads_rust) is an agent-first, per-project task tracker backed by SQLite + JSONL. proto integrates with it natively via the task_* tools.

Install


cargo install beads_rust

How it works

Issue data is stored in .beads/beads.db in your project root
Data is also flushed to JSONL for portability
br auto-discovers the database by walking up from the current directory — all commands work from any subdirectory
proto’s br skill initializes a workspace on first use via br init

Global flags

Flag	Description
`--json`	Machine-readable JSON output
`--db <PATH>`	Override database path
`--actor <NAME>`	Actor name for audit trail
`--no-color`	Disable ANSI color
`-q`, `--quiet`	Suppress all output except errors
`-v`, `--verbose`	Increase verbosity (repeat for `-vv`)
`--allow-stale`	Skip freshness check warning
`--lock-timeout <MS>`	SQLite busy timeout in ms
`--no-auto-flush`	Skip JSONL export after writes
`--no-auto-import`	Skip JSONL import check on startup

Workspace management


br init          # initialize .beads/ workspace
br where         # print .beads/ path
br info          # show diagnostics (db path, issue count, prefix)
br doctor        # run diagnostics and repair
br upgrade       # upgrade br in-place

Config


br config list               # all config options
br config get <key>          # get a value
br config set <key> <value>  # set a value
br config delete <key>       # remove a value
br config edit               # open in $EDITOR
br config path               # show config file locations

Key config options:


issue_prefix: proto # prefix for auto-generated IDs
default_priority: 2 # 0=critical … 4=backlog
default_type: task

Create issues


br create "Fix the login bug" -t bug -p 1 -d "Users see blank screen after 3 failed attempts"

Flag	Short	Type	Description
`--title`	—	string	Issue title (1–500 chars)
`--type`	`-t`	string	`task`, `bug`, `feature`, `epic`, `chore`, `docs`, `question`
`--priority`	`-p`	0–4 or P0–P4	0=critical, 4=backlog
`--description`	`-d`	string	Body / detailed description
`--assignee`	`-a`	string	Assign to a person

List and search


br list                          # list all open issues
br list -s open                  # filter by status
br list -t bug                   # filter by type
br list -p 0                     # filter by priority
br list --assignee alice          # filter by assignee
br list --json | jq '.[] | .id'  # machine-readable output
br search "login"                # full-text search

View an issue


br show <ID>
br show <ID> --json

Update issues


br update <ID> --status in-progress
br update <ID> --priority 0
br update <ID> --assignee bob
br update <ID> --title "New title"

Status values: open, in-progress, review, done, cancelled, blocked.

Close / resolve


br close <ID>
br resolve <ID>

Claim (agent task assignment)


br claim <ID> --actor agent-01   # atomically claim an issue
br unclaim <ID>                  # release a claim

Claiming is atomic — only one agent can claim an issue at a time. Used by proto for multi-agent task coordination.

Epics


br epic create "Auth refactor" --description "..."
br epic list
br epic add <ISSUE_ID> --epic <EPIC_ID>    # add issue to an epic
br epic show <EPIC_ID>

Export / import


br export                        # flush DB to JSONL
br import                        # re-import from JSONL
br export --format csv > issues.csv

proto integration

proto uses br via the task_create, task_update, task_list, task_get, task_ready, task_output, and task_stop tools. These map directly to br operations.

The br skill (/skills br) bootstraps a workspace and provides proto with instructions for claiming and updating tasks in multi-agent workflows.

Beads Task Tracker (br)