a lightweight, repo-local, multi-agent capable issue tracker.
status: ready for early users — feedback welcome! open an issue or reach out.
takes inspiration from beads.
- issues in git — markdown files versioned alongside code, no external service
- dependency tracking — issues can block other issues;
brd readyshows what's unblocked - multi-agent ready — claim-based workflow prevents duplicate work across parallel agents
- simple cli — partial ID matching, intuitive commands, works like you'd expect
| braid | beads | |
|---|---|---|
| storage | markdown files in .braid/issues/ |
jsonl in .beads/ |
| sync | git-native, no daemon required | auto-sync daemon, sqlite cache |
| focus | minimal cli, multi-agent workflows | rich ecosystem, hierarchical issues |
| size | ~9k lines of Rust (+7k tests) | ~71k lines of Go (+60k tests) |
curl -sSL https://raw.githubusercontent.com/alextes/braid/main/install.sh | bashdownloads a prebuilt binary (no rust required).
cargo install braidrequires rust 1.85+.
download the latest release from GitHub Releases.
# initialize in your repo (follow the prompts, or use -y for defaults)
cd your-project
brd init
# create your first issue
brd add "my first task" -p P1
# start working
brd startbrd init asks two questions: where to store issues and whether to auto-sync with git. the defaults work well for most setups.
brd init— initialize braid in current repobrd add "<title>" [-p P0-P3] [-b "<body>"] [--dep <id>] [--tag <tag>] [--scheduled-for <date>]— create a new issuebrd ls [--status open|doing|done|skip] [-p P0-P3] [--ready] [--blocked] [--scheduled]— list issuesbrd show <id> [--context]— show issue details (with--context: include deps and dependents)brd set <id> <field> <value>— quickly update a field (priority, status, type, owner, title, tag)brd edit <id>— open issue in $EDITORbrd rm <id>— delete an issue
brd start [<id>]— start working on an issue (auto-syncs, commits, and pushes the claim)brd done <id>— mark issue as donebrd skip <id>— mark issue as skipped (won't do)brd ready— list issues ready to work on
brd dep add <blocked> <blocker>— blocked depends on blockerbrd dep rm <blocked> <blocker>— remove dependency
brd agent init <name>— set up a new agent worktreebrd agent merge— merge to main (rebase + fast-forward)
brd tui— interactive terminal UI for browsing and managing issuesbrd commit— commit .braid changes with auto-generated messagebrd search— show how to search issues with grep/rgbrd doctor— validate repo statebrd status— show repo status summarybrd completions <shell>— generate shell completions
braid is configured via .braid/config.toml. key options:
id_prefix— prefix for issue IDs (default: derived from repo name)id_len— length of random suffix, 4-10 (default: 4)
see docs/configuration.md for full details.
braid enables multiple AI agents to work on the same codebase in parallel without stepping on each other's toes.
# enable issues-branch for instant visibility between agents
brd config issues-branch braid-issues
# create two tasks
brd add "implement feature A"
brd add "implement feature B"
# set up two agent worktrees
brd agent init agent-one
brd agent init agent-two
# in each worktree, tell the agent to pick up work
cd .worktrees/agent-one && brd start # claims feature A
cd .worktrees/agent-two && brd start # claims feature B (not A!)each agent automatically claims a different issue — no conflicts, no coordination needed.
- each agent gets their own git worktree via
brd agent init <name> - when an agent runs
brd start, the issue is marked as "doing" with their agent ID - with
issues-branchset, all agents see claims instantly (shared filesystem) - with issues stored with code, claims sync via git push/pull (optimistic locking)
# agent picks up work
brd start # claims next ready issue
# agent does the work and commits
git add . && git commit -m "feat: implement the thing"
# agent marks done and ships
brd done <id>
brd agent merge # rebase + fast-forward merge to mainbraid's workflow is controlled by two independent settings: issue storage and auto-sync. check your current config with brd config.
| storage | auto-sync | use case |
|---|---|---|
| with code | on | solo, remote agents |
| separate branch | on | multiple local agents |
| external repo | varies | privacy, multi-repo |
issues with code: issues live in .braid/issues/ and sync via git push/pull.
separate branch: issues live on a dedicated branch in a shared worktree — all local agents see changes instantly.
external repo: issues live in a separate repository entirely.
# enable issues-branch (separate branch)
brd config issues-branch braid-issues
# point to external repo (external repo must exist and be initialized with brd init)
brd config external-repo ../my-issues-repo
# disable issues-branch (issues with code)
brd config issues-branch --clear
# enable/disable auto-sync
brd config auto-sync on
brd config auto-sync offsee docs/workflow-modes.md for details.
beyond regular issues, braid supports two special types for structuring complex projects:
design issues (--type design) require human collaboration before closing. use them for:
- architecture decisions that need discussion
- trade-off analysis between approaches
- features that need human sign-off
agents should research and write up options, but wait for human approval before marking done.
brd add "decide on auth strategy" --type designmeta issues (--type meta) track groups of related work. they show progress as "done/total" in brd ls and are typically not worked on directly — instead, work on the child issues.
brd add "user authentication epic" --type meta
brd add "implement login endpoint" --dep <meta-id>
brd add "implement logout endpoint" --dep <meta-id>tag issues to categorize and filter them. tags starting with #bug render in red.
brd add "fix login crash" --tag bug
brd add "refactor auth module" --tag tech-debt --tag auth
brd ls --tag bugschedule issues to become ready at a future date. scheduled issues won't appear in brd ready or regular brd ls until their scheduled date passes.
# create a scheduled issue
brd add "update dependencies" --scheduled-for 2025-02-15
brd add "weekly review" --scheduled-for +7d
brd add "tomorrow's task" --scheduled-for tomorrow
# view scheduled issues
brd ls --scheduled
# modify scheduling
brd set <id> scheduled-for +30d
brd set <id> scheduled-for - # clear (makes it immediately available)supported date formats:
- ISO date:
2025-02-15(midnight UTC) - relative days:
+7d - relative weeks:
+2w - relative months:
+1mo tomorrow
braid includes a v early terminal UI for browsing and managing issues. launch it with brd tui.
the dashboard shows:
- status overview — open, doing, done, and skipped issue counts
- priority breakdown — P0-P3 distribution across active issues
- health metrics — ready vs blocked issues, stale work detection
- velocity — 7-day completion and creation sparklines
- git graph — branch relationships and commits across agent worktrees
- active agents — who's working on what
use number keys to switch views: 1 dashboard, 2 issues, 3 agents. press ? for help.