|
| 1 | +# Bridge |
| 2 | + |
| 3 | +A local-only task list that persists across repos and AI sessions. |
| 4 | + |
| 5 | +Bridge is a dependency-aware task manager that persists globally across repos and sessions. It gives AI coding agents (and you) a shared view of what needs to be done, what's blocked, and what's ready to work on. It is designed only for local, and as such, has no concept of git or remote syncing. |
| 6 | + |
| 7 | + |
| 8 | +## Why |
| 9 | + |
| 10 | +Dev workflows often live across multiple AI coding sessions. It can be helpful to have a place to manage them. Keeping track of a project in a single file means all sub-agents have to read the whole file. Sometimes and agent doesn't need the whole picture, but a peice. This is a task manager similar to beads that allows you to manage tasks for usage across sessions. This means sessions can either: |
| 11 | +a) assign work to eachother |
| 12 | +b) store "future work" of stuff to be done without effecting current session |
| 13 | +c) pick up "work to be done" without you have to copy/paste or reference a file. |
| 14 | + |
| 15 | + |
| 16 | +## Features |
| 17 | + |
| 18 | +- **Global task list**: tasks aren't scoped to a repo, they follow you everywhere |
| 19 | +- **Dependencies**: tasks can have dependencies, so you can mark things to NOT be worked on until other work is completed |
| 20 | +- **Priority + tags** — organize however you want with tags. Set priorities. |
| 21 | +- **Agent integration** — optional Claude Code plugin with slash commands (`/br:next`, `/br:plan`, `/br:add`) |
| 22 | +- **Fast CLI** — single binary, no runtime dependencies, prefix-matching IDs |
| 23 | + |
| 24 | +## Install |
| 25 | + |
| 26 | +Download the latest binary from [Releases](https://github.com/nhumrich/bridge/releases): |
| 27 | + |
| 28 | +```sh |
| 29 | +# Linux (amd64) |
| 30 | +curl -L https://github.com/nhumrich/bridge/releases/latest/download/br-linux-amd64 -o ~/.local/bin/br |
| 31 | +chmod +x ~/.local/bin/br |
| 32 | +``` |
| 33 | + |
| 34 | +I also recommend you add something to your CLAUDE/AGENTS.md so it knows to use `br`, such as: |
| 35 | + |
| 36 | +```markdown |
| 37 | +## Task Management |
| 38 | +We track work in Bridge (`br`) — a global task manager. Run `br --help` to see commands. |
| 39 | + |
| 40 | +### br Workflow |
| 41 | + 1. Check what's ready: `br ready` |
| 42 | + 2. Add tasks: `br add "task description" -p 0` (0=highest priority) |
| 43 | + 3. Add dependencies: `br dep <parent-id> <child-id>` (child blocks parent) |
| 44 | + 4. Start work: `br start <id>` |
| 45 | + 5. Complete work: `br close <id>` |
| 46 | + |
| 47 | + ### br Best Practices |
| 48 | + - Break down complex tasks into multiple issues with dependencies |
| 49 | + - Use `br ready` to see unblocked work before starting |
| 50 | + - Tags use `namespace:value` convention (e.g., `repo:bridge`, `feature`, `bug`) |
| 51 | + - Use `-t tag` to filter by tag |
| 52 | + - Use `br show <id>` for task details |
| 53 | +``` |
| 54 | + |
| 55 | +### Agent integration (optional) |
| 56 | + |
| 57 | +```sh |
| 58 | +br install # installs Claude Code slash commands |
| 59 | +br uninstall # removes them |
| 60 | +``` |
| 61 | + |
| 62 | +## Usage |
| 63 | + |
| 64 | +``` |
| 65 | +br add "my task" -p 0 # add task (priority 0 = highest) |
| 66 | +br add "fix bug" -t repo:bridge # add with tag |
| 67 | +br ready # show unblocked tasks |
| 68 | +br start <id> # start working |
| 69 | +br close <id> # complete task |
| 70 | +br dep add <blocker> <blocked> # add dependency |
| 71 | +br blocked # show what's stuck |
| 72 | +br ls # list open tasks |
| 73 | +br stats # overview |
| 74 | +``` |
| 75 | + |
| 76 | +Run `br --help` for all commands. |
| 77 | + |
| 78 | +# Tags |
| 79 | +Bridge supports tags. Tags are a very loosely opinionated system that lets you break down work however you want. You can tag things simply such as `[feature] [projecta]` or, you can use `:` notation for categories such as `repo:backend`, `repo:frontend`, `type:epic`, `project:foobar`, whatever you want. Just update your AI commands and workflows to tell it how you want to organize, and it does a good job. |
| 80 | +Also, putting `[]` around labels seems to work pretty well. For example: |
| 81 | +`create a task on br [feature repo:other]` |
| 82 | + |
| 83 | +AI will figure out `[featue repo:other]` means add those two tags. |
| 84 | + |
| 85 | +# Tricks |
| 86 | +I like to run `/br:plan` after a plan mode _instead of hitting accept plan_. It breaks the plan down into smaller steps. I then use `/clear` and `/br:next` and then the agent will pick up the work, and run the different tasks in parallel, each one only having the context of what it needs. |
| 87 | + |
| 88 | +I also sometimes like to keep adding tasks this way in a loop, while a different session picks up tasks from the "backlog" in a loop. |
| 89 | + |
| 90 | +## Build from source |
| 91 | + |
| 92 | +Requires [Pact](https://github.com/nhumrich/pact). |
| 93 | +```sh |
| 94 | +pact build src/main.pact |
| 95 | +cp build/main ~/.local/bin/br |
| 96 | +``` |
| 97 | + |
| 98 | +## License |
| 99 | + |
| 100 | +MIT |
| 101 | + |
| 102 | +## Etymology |
| 103 | + |
| 104 | +The bridge of a spaceship. It also bridges context between sessions. |
0 commit comments