beads-br 是基于 beads_rust（命令 br）的本地优先问题跟踪器，面向 AI 智能体管理任务、依赖、就绪工作，并通过 git JSONL 同步。br 不侵入版本控制：它从不运行 git 命令，同步与提交均由使用者负责，因此需显式执行 sync and commit。
使用方式：解析输出时始终加 --json；同步为显式操作，变更后运行 BEADS_DIR="$(ao beads dir)" br sync --flush-only；写入命令需失败关闭式解析，使用 BEADS_DIR="$(ao beads dir --require)"。常用命令包括 create、update --claim、close、reopen、ready --json、list --json、blocked --json、search、show、dep add/tree/cycles、sync --flush-only/--import-only、doctor、config --list。优先级 0 到 4 分别表示 Critical、High、Medium（默认）、Low、Backlog。
不要运行裸 bv，它会启动阻塞式 TUI；应使用 --robot-next、--robot-triage、--robot-plan 等标志。私有账本仓库 _beads/ 是独立 git 仓库，不要从宿主公开仓库暂存该账本。bd 作为跟踪器已退役，除 Gas City 明确豁免场景外不要在 br 仓库中运行 bd。多智能体协调可用 bead ID 作为 thread_id，共享数据库查询建议按仓库前缀过滤以防串项。关闭问题需在功能合并到 trunk 且可见于 origin/main 后，附上验证命令与原因。限制包括：不允许依赖环，br dep cycles 必须为空；坏 BEADS_DIR 可能导致写入回退跟踪器，因此写入需 --require；JSONL 是导出而非主要读取界面，实时读取以 br show/ready/list 为准。