bdtui 0.7.2 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +189 -165
- package/README.md +117 -95
- package/bin/bdtui.js +35 -35
- package/package.json +48 -48
- package/src/app.js +617 -586
- package/src/bd.js +130 -130
- package/src/keys.js +100 -98
- package/src/state.js +218 -218
- package/src/views/detail.js +231 -218
- package/src/views/list.js +99 -99
- package/src/views/modals.js +269 -255
package/CHANGELOG.md
CHANGED
|
@@ -1,165 +1,189 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to this project will be documented in this file.
|
|
4
|
-
|
|
5
|
-
## [Unreleased]
|
|
6
|
-
|
|
7
|
-
## [0.
|
|
8
|
-
|
|
9
|
-
### Added
|
|
10
|
-
|
|
11
|
-
- `w`
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
## [0.
|
|
24
|
-
|
|
25
|
-
###
|
|
26
|
-
|
|
27
|
-
- The
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
|
|
31
|
-
## [0.7.
|
|
32
|
-
|
|
33
|
-
### Added
|
|
34
|
-
|
|
35
|
-
- `
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
- `h`
|
|
74
|
-
- `
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
-
|
|
81
|
-
|
|
82
|
-
###
|
|
83
|
-
|
|
84
|
-
- `
|
|
85
|
-
|
|
86
|
-
## [0.
|
|
87
|
-
|
|
88
|
-
###
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
- `
|
|
99
|
-
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
-
|
|
124
|
-
|
|
125
|
-
## [0.
|
|
126
|
-
|
|
127
|
-
###
|
|
128
|
-
|
|
129
|
-
-
|
|
130
|
-
|
|
131
|
-
## [0.
|
|
132
|
-
|
|
133
|
-
###
|
|
134
|
-
|
|
135
|
-
-
|
|
136
|
-
|
|
137
|
-
## [0.
|
|
138
|
-
|
|
139
|
-
###
|
|
140
|
-
|
|
141
|
-
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
## [0.8.1] - 2026-10-29
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- The `w` workflow-command picker is split into two sections: **Claude skills** (the existing executor commands) and **OpenCode skills** (the same commands with an `opencode` argument, e.g. `/executor-task be-12 opencode`), for agent-workflow-beads ≥ 1.2.0's OpenCode implementor: Claude delegates only the implementation step to a headless OpenCode session. Section titles cannot be selected, and the cursor starts on the first command. The picker is widened from 56 to 66 columns so the longer lines are not truncated.
|
|
12
|
+
- Clicking a bead in the list (or scrolling the list with the mouse wheel) now shows its details in the Detail pane. Before, only keyboard navigation updated it.
|
|
13
|
+
- vi-style scrolling in the focused Detail pane: `j` / `k` scroll one line, `g` / `Shift+g` jump to the top / bottom, and `Ctrl-d` / `Ctrl-u` scroll half a page. Before, only `↑` / `↓` worked.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
|
|
17
|
+
- The `w` workflow-command picker colors each command: the skill name is green, the bead id is gray, and the `opencode` argument is red. The copied command is still plain text.
|
|
18
|
+
|
|
19
|
+
### Fixed
|
|
20
|
+
|
|
21
|
+
- The mouse wheel no longer stops working on the right side of the Detail pane in wide terminals. blessed only asked for X10/UTF-8 (`?1005`) mouse reports. X10 can't encode columns past 223, and xterm.js (the VS Code terminal) ignores `?1005`, so the terminal dropped those events. bdtui now also asks for SGR (`?1006`) reports, which have no column limit.
|
|
22
|
+
|
|
23
|
+
## [0.8.0] - 2026-07-02
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- The detail pane now shows a **Close Reason** section for closed beads. When a bead is closed with `c`, `bd` stores the text in its `close_reason` field; that resolution (with the close date) was already fetched but never displayed. It now renders above the dependencies, so you can see why/how a bead was closed without leaving the TUI.
|
|
28
|
+
- `m` toggles mouse capture so you can **select and copy detail-pane text**. blessed grabs the terminal mouse process-wide the moment any pane enables it, which blocks the terminal's own click-drag selection. Pressing `m` releases the mouse (drag to select, then copy with your terminal's copy); pressing it again restores wheel scrolling and click-to-select. The status bar shows the current mode.
|
|
29
|
+
- A **Deferred** status tab, added to the left of **Blocked** in the tab bar. It lists every bead whose stored status is `deferred` (`bd list --status deferred`) — beads you've explicitly parked — so they're reachable without scrolling the **All** tab. Like the other status tabs it builds the epic→child tree (a deferred bead nests under its parent epic) and cycles with `Tab` / `Shift+Tab`. The deferred status glyph/color and the `s` status picker already supported `deferred`; this surfaces it as a first-class view.
|
|
30
|
+
|
|
31
|
+
## [0.7.2] - 2026-06-29
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
- `w` now works on epics. Previously the workflow-command picker was disabled for epics ("workflow skills apply to tasks only"); pressing `w` on an epic now opens a picker offering `/executor-epic-sequential` and `/executor-epic-sequential-worktree` (which run every ready child of the epic on a single branch / isolated worktree). Tasks, chores, and bugs keep their existing per-bead executors.
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- `bd` errors now render as readable text in the status bar. When a `bd` command failed, bdtui threw the entire structured JSON error body (`{"error": "…", "schema_version": 1}`) verbatim — a multi-line blob whose leading `{` corrupted the one-line status bar markup (the "error with `{`" seen when a tab failed to load). bdtui now parses that body and surfaces just the human-readable `error` field, collapsing newlines and escaping tag markup so the status bar stays a clean single line.
|
|
40
|
+
- Tag-escaping no longer mangles text containing a literal `}`. The two-step escape (`replace('{')` then `replace('}')`) re-processed the `}` it had just inserted into `{open}`, turning any `}` in a bead description (e.g. JSON/code snippets) or in a `/` search query into a stray `{open}` token. Escaping is now a single pass in both the detail pane and the status bar.
|
|
41
|
+
|
|
42
|
+
### Changed
|
|
43
|
+
|
|
44
|
+
- npm package metadata: expanded `description` and added `keywords` for discoverability; normalized the repository URL to the `git+https://` form.
|
|
45
|
+
- Removed internal agent-workflow tooling (`.beads/`, `.claude/` agents and skills, `CLAUDE.md`, `BEADS_WORKFLOW.md`, `docs/TROUBLESHOOTING.md`) from the repository.
|
|
46
|
+
|
|
47
|
+
## [0.7.1] - 2026-06-21
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
|
|
51
|
+
- The **Keybindings** (`?`) help can now be dismissed after a mouse click moves focus to the Beads list or Detail pane. Its close keys were bound to the help box itself, so once a click stole focus the modal became unclosable (every global key is suppressed while a modal is open). `q`/`Esc`/`h` are now bound at the screen level and dismiss it regardless of which pane holds focus.
|
|
52
|
+
- Reopening the Keybindings help with `?` works again. `?` is now a single open/close toggle, fixing a re-entrancy where the freshly-registered `?` close handler fired on the very keypress that opened the modal and slammed it shut.
|
|
53
|
+
- The boot status bar no longer shows the `? help` hint twice. `setStatus` already appends it, so the redundant hint baked into the "Ready" message was removed.
|
|
54
|
+
|
|
55
|
+
## [0.7.0] - 2026-06-21
|
|
56
|
+
|
|
57
|
+
### Added
|
|
58
|
+
|
|
59
|
+
- `Shift+r`: reset all narrowing filters (title search, epic scope, type) and reload fresh.
|
|
60
|
+
- The status bar now summarizes every active narrowing filter together — e.g. `"login" · epic: bd-12 · type: task — 3 results | Shift+r to reset` — instead of only the most recent one. The epic filter now shows the same result-count/reset hint that title search did.
|
|
61
|
+
- The tab bar gains a persistent `search:` indicator for the active title filter, alongside the existing `type:` and `epic:` indicators.
|
|
62
|
+
|
|
63
|
+
### Changed
|
|
64
|
+
|
|
65
|
+
- `r` (reload) now **keeps** active filters instead of clearing the epic filter; use `Shift+r` to clear filters. This reverses the `0.5.0` behavior where `r` cleared the epic filter.
|
|
66
|
+
- The `/` title filter is now persistent state: it survives a reload (`r`) and composes with the epic and type filters. The prompt pre-fills with the current search, and submitting an empty value clears just the title filter.
|
|
67
|
+
|
|
68
|
+
### Fixed
|
|
69
|
+
|
|
70
|
+
- `Shift+c` (claim) and `Shift+g` (jump to bottom) now actually fire. They were registered as bare uppercase `C`/`G`, but blessed reports a shifted letter as `S-<lower>`, so the handlers were dead — claim did nothing and `Shift+g` only reached the last *loaded* page instead of revealing all rows and jumping to the true bottom.
|
|
71
|
+
- Reloading or filtering while scoped to an epic on the **All**/**Closed** tabs no longer caps the fetch at bd's default 50 rows, which could drop an epic's children from the scoped view.
|
|
72
|
+
- The title search is now tag-escaped before it reaches the status bar, so a query containing `{`/`}` no longer corrupts the status line.
|
|
73
|
+
- Reparenting with `h` no longer throws `Unexpected token '✓' … is not valid JSON`. `bd dep add`/`bd dep remove` print a human-readable line rather than JSON, so their output is no longer parsed as JSON.
|
|
74
|
+
- `h` (change parent) now **detaches every existing parent first, then attaches** the chosen one — previously it added the new parent before removing the old, so the JSON error above left the bead with two parents. It also clears *all* existing parent-child links (not just the first), repairing beads that already ended up with multiple parents.
|
|
75
|
+
|
|
76
|
+
## [0.6.0] - 2026-06-14
|
|
77
|
+
|
|
78
|
+
### Fixed
|
|
79
|
+
|
|
80
|
+
- The **Closed** and **All** tabs now render the epic→children tree like the other tabs; previously they showed a flat, ungrouped list with every bead at the top level. Closed children nest under their epic (parent epics that aren't themselves closed are pulled in as the grouping anchor).
|
|
81
|
+
|
|
82
|
+
### Changed
|
|
83
|
+
|
|
84
|
+
- Tree views now build from the `parent` field that `bd` embeds in each `bd list`/`bd ready` row instead of fetching one `bd dep list` per bead. The Closed/All tabs gain the tree at no extra per-bead subprocess cost (lazy "load more" pagination is unchanged), and the Ready/Blocked/In-progress tabs load with fewer `bd` calls. The Blocked tab keeps a per-row `bd dep list` fallback for the derived-blocked rows `bd blocked` returns without a `parent` field.
|
|
85
|
+
|
|
86
|
+
## [0.5.1] - 2026-06-14
|
|
87
|
+
|
|
88
|
+
### Fixed
|
|
89
|
+
|
|
90
|
+
- Blocked tab now also lists beads whose status was explicitly set to `blocked`. Previously it ran only `bd blocked` (which returns *derived*-blocked beads — open beads with unclosed blockers), so explicitly-blocked beads were missing from the tab; the filter now merges `bd blocked` with `bd list --status blocked`.
|
|
91
|
+
- List rows for open beads that are derived-blocked now show the `blocked` status label and color, matching the detail view's effective-status logic.
|
|
92
|
+
|
|
93
|
+
## [0.5.0] - 2026-06-13
|
|
94
|
+
|
|
95
|
+
### Added
|
|
96
|
+
|
|
97
|
+
- `h` key: dedicated parent-picker to reparent a bead under a different epic or detach it as standalone (epics listed newest-updated-first; current parent excluded).
|
|
98
|
+
- `chore` and `bug` added to the `t` type-filter cycle (`all → epic → task → chore → bug → all`).
|
|
99
|
+
- `x` key in the epic-filter picker clears the filter immediately (same as selecting ✗ Clear).
|
|
100
|
+
|
|
101
|
+
### Changed
|
|
102
|
+
|
|
103
|
+
- All tabs now sort beads by `updated_at` DESC (most-recently-touched first), preserving the epic→children tree grouping for tree tabs and ordering children within each epic the same way.
|
|
104
|
+
- `r` (reload) now also clears any active epic filter before reloading; status bar shows "Epic filter cleared" when it does.
|
|
105
|
+
|
|
106
|
+
### Removed
|
|
107
|
+
|
|
108
|
+
- `D` dependency menu — replaced by the focused `h` reparent picker.
|
|
109
|
+
|
|
110
|
+
## [0.4.0] - 2026-06-07
|
|
111
|
+
|
|
112
|
+
### Added
|
|
113
|
+
|
|
114
|
+
- Lazy pagination for the `all` and `closed` tabs: every bead loads in a single `bd` call (flat, no per-bead dependency fetch) and rows are revealed in batches as you scroll to the bottom, with a "showing X of Y" count. This lifts the previous silent 50-row cap so the full history is reachable. `G` jumps to the true bottom; `/` searches the whole list.
|
|
115
|
+
|
|
116
|
+
### Changed
|
|
117
|
+
|
|
118
|
+
- Epic filter picker now lists the most recently created epics first.
|
|
119
|
+
|
|
120
|
+
### Fixed
|
|
121
|
+
|
|
122
|
+
- `stdout maxBuffer length exceeded` error when a `bd list` payload exceeded 1 MB (e.g. the `all` tab on a large repo) — the output buffer is now 64 MB.
|
|
123
|
+
- Epic filter picker could miss epics beyond the first 50 results; it now enumerates all epics.
|
|
124
|
+
|
|
125
|
+
## [0.3.2] - 2026-05-24
|
|
126
|
+
|
|
127
|
+
### Changed
|
|
128
|
+
|
|
129
|
+
- Detail-pane dependency rows redesigned: status-colored icons (○ open, ◐ in_progress, ● blocked, ✓ closed, ❄ deferred) with the whole row tinted by effective status. Open beads whose blockers aren't all closed now render as blocked, mirroring how `bd blocked` derives the Blocked tab.
|
|
130
|
+
|
|
131
|
+
## [0.3.1] - 2026-05-16
|
|
132
|
+
|
|
133
|
+
### Added
|
|
134
|
+
|
|
135
|
+
- Auto-start Dolt on launch: `bdtui` runs `bd dolt test` and falls back to `bd dolt start` if the project's Dolt server is down, so the TUI no longer opens against a dead backend. Skipped for `-v`/`--version`.
|
|
136
|
+
|
|
137
|
+
## [0.3.0] - 2026-05-15
|
|
138
|
+
|
|
139
|
+
### Added
|
|
140
|
+
|
|
141
|
+
- `e` shortcut: filter the list by epic via a modal picker; selecting an epic scopes the view to that epic and its children, with an option to clear the filter
|
|
142
|
+
|
|
143
|
+
## [0.2.3] - 2026-05-13
|
|
144
|
+
|
|
145
|
+
### Added
|
|
146
|
+
|
|
147
|
+
- `bdtui -v` / `bdtui --version` prints the current version and exits
|
|
148
|
+
|
|
149
|
+
## [0.2.2] - 2026-05-11
|
|
150
|
+
|
|
151
|
+
### Added
|
|
152
|
+
|
|
153
|
+
- `repository`, `homepage`, and `bugs` fields in package.json — GitHub link now visible on npmjs.com
|
|
154
|
+
|
|
155
|
+
## [0.2.1] - 2026-05-11
|
|
156
|
+
|
|
157
|
+
### Fixed
|
|
158
|
+
|
|
159
|
+
- Screenshot not rendering on npmjs.com — switched to absolute GitHub raw URL
|
|
160
|
+
|
|
161
|
+
## [0.2.0] - 2026-05-11
|
|
162
|
+
|
|
163
|
+
### Fixed
|
|
164
|
+
|
|
165
|
+
- Clipboard action stuck at "Copying" after the first use — now resolves on stdin flush instead of waiting for daemon processes (`wl-copy`, `xclip`) to exit
|
|
166
|
+
|
|
167
|
+
### Changed
|
|
168
|
+
|
|
169
|
+
- `blocked` tab now uses `bd blocked` (dependency-blocked issues) instead of `bd list --status blocked`
|
|
170
|
+
- Workflow skill picker renamed to "Copy workflow command" and positioned on the left side of the screen
|
|
171
|
+
- Detail pane field rows use a `│` column separator with consistent alignment across all rows
|
|
172
|
+
|
|
173
|
+
### Added
|
|
174
|
+
|
|
175
|
+
- Screenshot in README
|
|
176
|
+
|
|
177
|
+
## [0.1.0] - 2026-04-28
|
|
178
|
+
|
|
179
|
+
### Added
|
|
180
|
+
|
|
181
|
+
- Initial MVP: blessed two-pane TUI (list + detail) for `bd`
|
|
182
|
+
- Tree view grouping tasks under their parent epic
|
|
183
|
+
- Status and type filter tabs with keyboard cycling
|
|
184
|
+
- Rich color scheme for status, priority, and dependency lines
|
|
185
|
+
- Inline markdown rendering in description, acceptance, and notes fields
|
|
186
|
+
- Mutation keys: change status, close, claim, reopen, change priority, manage deps
|
|
187
|
+
- `y` to yank bead ID to clipboard, `w` to copy a workflow skill command
|
|
188
|
+
- In-memory title filter (`/`)
|
|
189
|
+
- Help overlay (`?`)
|
package/README.md
CHANGED
|
@@ -1,95 +1,117 @@
|
|
|
1
|
-
# bdtui
|
|
2
|
-
|
|
3
|
-
Fast blessed-based terminal UI for the [`bd`](https://github.com/gastownhall/beads) beads issue tracker.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
## Requirements
|
|
8
|
-
|
|
9
|
-
- Node ≥ 20
|
|
10
|
-
- `bd` installed and on `$PATH`
|
|
11
|
-
- A project with a `.beads/` database (created by `bd init`)
|
|
12
|
-
- (Optional) A clipboard helper for the `y` yank key:
|
|
13
|
-
- Linux/Wayland: `wl-clipboard` (`sudo apt install wl-clipboard`)
|
|
14
|
-
- Linux/X11: `xclip` (`sudo apt install xclip`) or `xsel`
|
|
15
|
-
- macOS: `pbcopy` (preinstalled)
|
|
16
|
-
- Windows: `clip.exe` (preinstalled on Windows 10/11)
|
|
17
|
-
|
|
18
|
-
## Install
|
|
19
|
-
|
|
20
|
-
First install `bd`:
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
brew install beads # macOS / Linux
|
|
24
|
-
npm install -g @beads/bd # via Node.js
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Then install bdtui:
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
npm install -g bdtui
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
## Usage
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
bdtui # use current directory
|
|
37
|
-
bdtui . # explicit current directory
|
|
38
|
-
bdtui ~/www/myapp # explicit project path
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## Layout
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
│
|
|
48
|
-
|
|
49
|
-
│
|
|
50
|
-
|
|
51
|
-
│
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
| `
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
1
|
+
# bdtui
|
|
2
|
+
|
|
3
|
+
Fast blessed-based terminal UI for the [`bd`](https://github.com/gastownhall/beads) beads issue tracker.
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Node ≥ 20
|
|
10
|
+
- `bd` installed and on `$PATH`
|
|
11
|
+
- A project with a `.beads/` database (created by `bd init`)
|
|
12
|
+
- (Optional) A clipboard helper for the `y` yank key:
|
|
13
|
+
- Linux/Wayland: `wl-clipboard` (`sudo apt install wl-clipboard`)
|
|
14
|
+
- Linux/X11: `xclip` (`sudo apt install xclip`) or `xsel`
|
|
15
|
+
- macOS: `pbcopy` (preinstalled)
|
|
16
|
+
- Windows: `clip.exe` (preinstalled on Windows 10/11)
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
First install `bd`:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
brew install beads # macOS / Linux
|
|
24
|
+
npm install -g @beads/bd # via Node.js
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Then install bdtui:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install -g bdtui
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Usage
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
bdtui # use current directory
|
|
37
|
+
bdtui . # explicit current directory
|
|
38
|
+
bdtui ~/www/myapp # explicit project path
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Layout
|
|
42
|
+
|
|
43
|
+
A top tab bar (the active status filter is highlighted — shown here as `[ready]` — followed by the live `type:` / `epic:` / `search:` and bead-count indicators), a two-pane body with the **Beads** list on the left and the **Detail** view on the right, and a bottom status bar:
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
┌──────────────────────────────────────────────────────────────────────────────────
|
|
47
|
+
│ deferred │ blocked │ [ready] │ in_progress │ closed │ all type: all · 27 beads
|
|
48
|
+
├──────────────────────────────────────────────────────────────────────────────────
|
|
49
|
+
│ Beads (27) │ Detail
|
|
50
|
+
│ be-12 P1 in_prog T Fix login │ be-12 — Fix login bug
|
|
51
|
+
│ be-13 P2 open T Retry │ ══════════════════════════════
|
|
52
|
+
│ be-10 P1 open E Auth epic │ Status: in_progress │ Priority: P1 High
|
|
53
|
+
│ be-11 P2 open T ├ OAuth │ Type: bug │ Owner: alice
|
|
54
|
+
│ be-14 P2 closed B └ CSRF │ Created: 2026-06-01 │ Updated: 2026-06-14
|
|
55
|
+
│ │
|
|
56
|
+
│ list · 40% │ detail · 60%
|
|
57
|
+
├───────────────────────────────────────────────────────────────────────────────────
|
|
58
|
+
│ ● Ready ? help · q quit
|
|
59
|
+
└───────────────────────────────────────────────────────────────────────────────────
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Each list row reads `id · priority · status · type-badge · title`. The detail pane shows the selected bead's fields, its close reason (for closed beads), dependencies, and rendered description.
|
|
63
|
+
|
|
64
|
+
Beads with parent–child dependencies are shown as a tree inside the active filter — child rows nest under their epic with `├` / `└`:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
be-10 P1 open E Auth epic
|
|
68
|
+
be-11 P2 open T ├ Add OAuth login
|
|
69
|
+
be-12 P2 open T └ Refresh tokens
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Keybindings
|
|
73
|
+
|
|
74
|
+
| Key | Action |
|
|
75
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
76
|
+
| `j` / `↓` | Move down |
|
|
77
|
+
| `k` / `↑` | Move up |
|
|
78
|
+
| `g` / `Shift+g` | Jump to top / bottom |
|
|
79
|
+
| `Enter` / `l` | Focus detail pane |
|
|
80
|
+
| `h` / `Esc` | Back to list (from detail) |
|
|
81
|
+
| `j` / `k` (detail) | Scroll detail pane when focused (`g` / `Shift+g` top / bottom, `Ctrl-d` / `Ctrl-u` half page) |
|
|
82
|
+
| `Tab` / `Shift+Tab` | Next / previous status filter (deferred/blocked/ready/in_progress/closed/all) |
|
|
83
|
+
| `t` | Cycle type filter (all/epic/task/chore/bug) |
|
|
84
|
+
| `e` | Filter by epic (modal picker; `x` clears) |
|
|
85
|
+
| `/` | In-memory title filter (empty submit clears it) |
|
|
86
|
+
| `r` | Reload (keeps active filters) |
|
|
87
|
+
| `Shift+r` | Reset all filters (title / epic / type) and reload |
|
|
88
|
+
| `s` | Change status |
|
|
89
|
+
| `c` | Close with reason |
|
|
90
|
+
| `Shift+c` | Claim (in_progress + assign self) |
|
|
91
|
+
| `o` | Reopen |
|
|
92
|
+
| `p` | Change priority |
|
|
93
|
+
| `h` | Change parent (epic / standalone) |
|
|
94
|
+
| `y` | Yank bead ID to clipboard |
|
|
95
|
+
| `w` | Pick a workflow command and copy it with the selected bead's ID. Tasks list the per-bead executors (`/executor-task`, `/executor-task-worktree`, `/executor-epic-task`, `/executor-epic-task-worktree`, `/executor-rework-in-place`); epics list `/executor-epic-sequential` and `/executor-epic-sequential-worktree`. The picker has two sections: **Claude skills** and **OpenCode skills** (the same commands with an `opencode` argument). See [Agent workflow](#agent-workflow). |
|
|
96
|
+
| `m` | Release mouse capture so you can drag-select & copy detail text with your terminal (toggle) |
|
|
97
|
+
| `?` | Help overlay |
|
|
98
|
+
| `q` / `Ctrl-C` | Quit |
|
|
99
|
+
|
|
100
|
+
## Agent workflow
|
|
101
|
+
|
|
102
|
+
Pressing `w` copies a slash-command for the selected bead, e.g. `/executor-task be-12`. Those `/executor-*` commands are [Claude Code](https://claude.com/claude-code) skills scaffolded by [`agent-workflow-beads`](https://www.npmjs.com/package/agent-workflow-beads) — a planner → executor workflow backed by the same beads database. Install it globally, then bootstrap your repo so the copied commands resolve:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npm install -g agent-workflow-beads
|
|
106
|
+
agent-workflow-beads bootstrap /path/to/your-repo myprefix
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The picker's **OpenCode skills** section lists the same commands with a trailing `opencode` (e.g. `/executor-task be-12 opencode`). That variant has Claude delegate the implementation step to a headless [OpenCode](https://opencode.ai) implementor while Claude still plans, tests, reviews, and closes the bead. It needs `opencode` on `PATH` and a repo scaffolded with `agent-workflow-beads bootstrap|update --with-opencode` (agent-workflow-beads ≥ 1.2.0). Append `model=<provider/model>` after pasting to pick the OpenCode model; otherwise OpenCode's default is used.
|
|
110
|
+
|
|
111
|
+
## Author
|
|
112
|
+
|
|
113
|
+
[JSIOVN](https://github.com/jsiovn)
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT
|