Bạn nhờ Claude Code làm một tính năng lớn. Hôm sau mở session mới, agent không còn nhớ gì: làm tới đâu, còn việc nào, việc nào phải xong trước. File TODO.md thì đã lệch so với code từ lúc nào không hay.
Bài này giới thiệu hai tool xử lý chuyện đó, cả hai cùng dựa trên Beads (bd). agent-workflow-beads cài một workflow planner → executor vào repo, còn bdtui cho bạn xem cả backlog trong terminal. Mọi lệnh, output và ảnh đều lấy từ một repo demo chạy thật.
Source code: jsiovn/agent-workflow-beads · jsiovn/bdtui · gastownhall/beads
1. Beads là gì và vì sao AI agent cần nó
Beads là một issue tracker dạng CLI (lệnh bd), thiết kế cho AI coding agent. Thay vì ghi việc vào file Markdown, mỗi việc là một bead nằm trong database ngay trong repo (thư mục .beads/). Agent đọc và ghi bead bằng lệnh bd, nên session nào mở ra cũng thấy cùng một trạng thái.
Bạn chỉ cần nắm bốn khái niệm:
| Khái niệm | Ý nghĩa |
|---|---|
| bead | Một việc cần làm: có ID, title, description, status, priority |
| epic | Bead “cha”, gom các task của cùng một tính năng |
| dependency | Quan hệ “bead B phải chờ bead A xong” |
| ready | Bead có status open và không còn bị bead nào chặn |
ready là lý do Beads hợp với agent. Thay vì tự đoán nên làm gì trước, agent chỉ cần gọi bd ready là nhận về những việc làm được ngay. Phần 4 sẽ cho bạn thấy danh sách này thay đổi thế nào.
Hai tool trong bài không thay thế bd mà chạy trên nền bd:
- agent-workflow-beads dạy agent cách làm việc với bead: plan thế nào, làm một bead ra sao, khi nào đóng.
- bdtui cho bạn nhìn và chỉnh bead mà không phải gõ từng lệnh
bd.
2. Cài đặt
Bạn cần Node.js ≥ 20, git, và hai tool nền là bd và dolt:
1
2
3
# bd (Beads CLI): chọn một trong hai
brew install beads # macOS / Linux
npm install -g @beads/bd # qua Node.jsTrên Windows, Beads có script cài riêng cho PowerShell:
1
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iexdolt cài theo hướng dẫn của Dolt cho từng hệ điều hành. Sau đó cài hai tool của bài:
1
2
npm install -g agent-workflow-beads
npm install -g bdtuiKiểm tra mọi thứ đã nằm trên PATH:
1
agent-workflow-beads check1
Required commands found: git, bd, doltBài này dùng bd 1.3.4, dolt 2.1.11, agent-workflow-beads 1.4.1 và bdtui 0.11.1.
Lưu ý: vì sao phải cài thêm dolt?
Beads lưu bead trong Dolt, một database có version control kiểu Git. agent-workflow-beads khởi tạo Beads ở server mode, nên máy bạn phải có sẵn lệnh dolt.
3. agent-workflow-beads: cài workflow vào repo bằng một lệnh
3.1. Chạy bootstrap
Lệnh bootstrap nhận hai tham số: đường dẫn repo và một prefix dùng làm tiền tố cho ID của bead. Mình thử với một repo trống tên todo-demo, prefix todo:
1
agent-workflow-beads bootstrap todo-demo todoOutput thật khá dài (110 dòng), mình lược bớt các đoạn lặp và đánh dấu bằng ...; đường dẫn tuyệt đối được rút gọn thành …:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Required commands found: git, bd, dolt
Repo: …\todo-demo
Prefix: todo
AI: Claude Code (primary); OpenCode and omp read the same skills
Agents: .claude/agents/
...
✓ bd initialized successfully!
Backend: dolt
Mode: server
...
Issue prefix: todo
Issues will be named: todo-<hash> (e.g., todo-a3f2dd)
...
✓ Registered SessionStart hook
...
Copied BEADS_WORKFLOW.md
Copied .beads/PRIME.md
Copied Claude build-and-test skill
Copied Claude skill: address-pr-comments
...
Copied shared agent: backend-architect.md
...
Updated .gitignore managed workflow block
Updated CLAUDE.md managed block
✓ Created issue: todo-dgm — Specialize build-and-test for this repo
Priority: P2
Status: open
...
✅ Bootstrap complete.Giải thích:
- Tool chạy
bd initvới prefixtodo, nên mọi bead của repo này có ID dạngtodo-xxx. - Nó đăng ký một hook
SessionStartcho Claude Code để chạybd prime, nên mỗi session mới agent đều được nạp sẵn hướng dẫn dùngbd. - Nó copy skill và subagent vào
.claude/, rồi thêm một block hướng dẫn vàoCLAUDE.md. - Cuối cùng nó tạo sẵn bead đầu tiên,
todo-dgm, nội dung là dạy agent cách build và test repo của bạn.
Nếu thư mục chưa phải Git repo, bootstrap sẽ tự git init trước.
3.2. Trong repo có thêm gì
1
2
3
4
5
6
7
8
9
todo-demo/
├── .beads/ # database Beads của repo
├── .claude/
│ ├── agents/ # 10 subagent: code-reviewer, product-manager, ...
│ ├── skills/ # 30 skill: plan-beads, executor-task, ...
│ └── settings.json # hook SessionStart
├── .gitignore
├── BEADS_WORKFLOW.md # mô tả workflow planner → executor
└── CLAUDE.md # hướng dẫn cho agentSkill là một quy trình viết sẵn mà bạn gọi bằng tên trong Claude Code, ví dụ /plan-beads. Subagent là một vai chuyên biệt (reviewer, architect, product manager) mà skill hoặc bạn gọi khi cần góc nhìn đó.
Các file này được commit vào Git như code bình thường, nên cả team và mọi branch đều dùng chung một workflow:
1
2
git add -A
git commit -m "chore: add agent-workflow-beads workflow surface"3.3. Hai loại session: planner và executor
Ý tưởng cốt lõi của workflow là tách việc lên kế hoạch khỏi việc viết code:
- Planner session biến một ý tưởng thành các bead có dependency rõ ràng. Session này không viết code.
- Executor session chỉ nhận một bead, làm xong, mở một pull request (PR) rồi đóng bead.
View Mermaid diagram code
flowchart TD
Idea(["Ý tưởng hoặc bug"]) --> Planner["Planner session: /plan-beads"]
Planner --> Beads["Beads: epic, task, dependency"]
Beads --> Ready{"bd ready"}
Ready --> Executor["Executor session: /executor-task"]
Executor --> PR(["Pull request"])
Executor -->|"đóng bead"| Beads
style Planner fill:#0e2233,stroke:#4aa8ff,stroke-width:1.5px,color:#9ecbff
style Beads fill:#241832,stroke:#c08cff,stroke-width:1.5px,color:#d4b3ff
style Executor fill:#1a2c08,stroke:#c7ff50,stroke-width:1.5px,color:#c7ff50Vì sao phải tách? Mỗi executor session bắt đầu với context sạch và chỉ đọc một bead, nên agent ít bị lan man sang việc khác. Đổi lại, bead phải ghi đủ thông tin để một session mới toanh làm được mà không cần đọc lại đoạn chat lúc plan.
Bạn không cần thuộc cả 30 skill. Sáu skill dưới đây đủ cho hầu hết công việc:
| Skill | Dùng khi |
|---|---|
/plan-beads | Có ý tưởng hoặc bug, muốn biến thành bead |
/validate-beads | Vừa plan xong một epic, muốn kiểm tra trước khi cho agent chạy |
/executor-task <bead-id> | Làm một bead trên branch riêng, mở PR vào main |
/executor-task-worktree <bead-id> | Như trên, nhưng trong một git worktree tách biệt |
/executor-epic-sequential <epic-id> | Chạy cả epic: mỗi bead một session mới, cuối cùng một PR |
/address-pr-comments | Reviewer vừa comment trên PR |
Danh sách đầy đủ nằm trong README của agent-workflow-beads.
4. Tạo vài bead để thử
Trong thực tế, /plan-beads sẽ tạo bead giúp bạn. Ở đây mình tạo bằng tay để bạn thấy thực chất nó chỉ là vài lệnh bd. Đầu tiên là một epic:
1
2
bd create "User login" --type epic --priority 1 \
--description "Let users sign in with email and password so each person sees only their own todos."1
2
3
✓ Created issue: todo-pfj — User login
Priority: P1
Status: openTiếp theo là các task con, gắn vào epic bằng --parent:
1
2
3
4
5
6
bd create "Create users table and migration" --parent todo-pfj --priority 1 \
--description "Add a users table (id, email, password_hash, created_at) and a migration script.
## Verify
- npm run migrate creates the table
- email column is unique"1
2
3
✓ Created issue: todo-pfj.1 — Create users table and migration
Priority: P1
Status: openMình tạo thêm ba task theo cùng cách (todo-pfj.2 tới todo-pfj.4). Lúc này bd ready trả về tất cả, vì chưa bead nào chặn bead nào. Giờ khai báo thứ tự bằng bd dep add <bead> <bead-phải-xong-trước>:
1
2
3
bd dep add todo-pfj.2 todo-pfj.1
bd dep add todo-pfj.3 todo-pfj.2
bd dep add todo-pfj.4 todo-pfj.31
2
3
✓ Added dependency: todo-pfj.2 (Add POST /login endpoint) depends on todo-pfj.1 (Create users table and migration) (blocks)
✓ Added dependency: todo-pfj.3 (Build login form) depends on todo-pfj.2 (Add POST /login endpoint) (blocks)
✓ Added dependency: todo-pfj.4 (Write login integration tests) depends on todo-pfj.3 (Build login form) (blocks)View Mermaid diagram code
flowchart LR
T1["todo-pfj.1<br/>users table"] --> T2["todo-pfj.2<br/>POST /login"]
T2 --> T3["todo-pfj.3<br/>login form"]
T3 --> T4["todo-pfj.4<br/>integration tests"]
style T1 fill:#1a2c08,stroke:#c7ff50,stroke-width:1.5px,color:#c7ff50
style T2 fill:#2a2008,stroke:#ffc043,stroke-width:1.5px,color:#ffd98a
style T3 fill:#2a2008,stroke:#ffc043,stroke-width:1.5px,color:#ffd98a
style T4 fill:#2a2008,stroke:#ffc043,stroke-width:1.5px,color:#ffd98aChạy lại bd ready:
1
bd ready1
2
3
4
5
6
7
8
9
10
○ todo-pfj P1 [epic] User login
○ todo-pfj.1 P1 Create users table and migration ← User login
○ todo-dgm P2 Specialize build-and-test for this repo
○ todo-27u P2 [bug] Todo list does not refresh after delete
--------------------------------------------------------------------------------
Ready: 4 issues with no active blockers
Status: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred
Priority: P0–P4 (label only; not a status icon)Giải thích:
- Trong epic chỉ còn
todo-pfj.1là ready. Ba task còn lại biến mất khỏi danh sách vì đang chờ task đứng trước. - Chỉ dependency loại
blocks(mặc định củabd dep add) mới ảnh hưởng tớiready. Quan hệ cha-con với epic thì không, nó chỉ dùng để gom nhóm. todo-27ulà một bug mình tạo riêng, không thuộc epic nào, nên nó ready ngay.- ID của bead là hash, nên trên máy bạn sẽ ra chuỗi khác.
5. bdtui: xem backlog ngay trong terminal
Gõ lệnh bd mãi thì cũng mỏi, nhất là khi backlog có vài chục bead. bdtui hiển thị tất cả trong một màn hình. Nó không có database riêng mà gọi lại bd cho mọi thao tác, nên bạn và agent luôn thấy cùng một dữ liệu.
1
2
cd todo-demo
bdtui5.1. Màn hình chính

Màn hình có ba phần:
- Tab bar trên cùng: lọc bead theo status (
deferred,blocked,ready,in_progress,closed,all). bdtui mở sẵn tabready, hiện bốn bead giống hệt kết quảbd readylúc nãy. - Beads bên trái: mỗi dòng gồm ID, priority, status, một chữ cái cho type (
Eepic,Ttask,Bbug,Cchore) và title. - Detail bên phải: toàn bộ thông tin của bead đang chọn, kể cả Depends on (nó chờ bead nào) và Needed by (bead nào chờ nó). bdtui liệt kê cả epic cha trong Depends on, dù quan hệ cha-con không chặn bead.
5.2. Những phím cần nhớ
bdtui dùng phím kiểu Vim. Bấm ? để xem đủ danh sách, còn đây là những phím bạn dùng hằng ngày:
| Phím | Tác dụng |
|---|---|
j / k | Xuống / lên trong danh sách |
Tab / Shift+Tab | Chuyển tab status |
Enter | Chuyển sang pane Detail để cuộn đọc description (Esc để quay lại) |
/ | Lọc theo title |
e | Lọc theo epic |
Shift+c | Claim bead: chuyển sang in_progress và gán cho bạn |
c | Đóng bead kèm lý do |
w | Copy lệnh workflow cho bead đang chọn (phần 6) |
q | Thoát |
Bạn cũng có thể click chuột vào tab, vào dòng bead hay vào dòng dependency.
5.3. Tab all: nhìn cả epic
Bấm Tab vài lần để sang tab all:

Các task con được vẽ thành cây ngay dưới epic todo-pfj. Ba task đang chờ hiện status blocked màu đỏ. Chọn todo-pfj.2, pane Detail cho biết nó chờ todo-pfj.1, và todo-pfj.3 thì đang chờ nó. Bạn đọc được cả chuỗi dependency mà không phải gõ lệnh nào.
6. Nối hai tool: phím w
Quay lại tab ready, chọn todo-pfj.1 rồi bấm w:

Với một task, bdtui liệt kê bốn lệnh executor đã gắn sẵn ID của bead: /executor-task, /executor-task-worktree, /executor-epic-task và /executor-epic-task-worktree. Bấm Enter ở dòng đầu, lệnh /executor-task todo-pfj.1 được copy vào clipboard. Bạn dán nó vào Claude Code, và skill executor-task (do agent-workflow-beads cài ở phần 3) sẽ lo phần còn lại: claim bead, viết plan, code, chạy build và test, tự review, mở PR rồi đóng bead.
Mình không dán transcript của agent vào đây, vì mỗi lần chạy sẽ ra một kiểu và nó phụ thuộc vào code của bạn. Để bạn thấy điều gì xảy ra sau khi bead xong, mình đóng todo-pfj.1 bằng tay:
1
2
bd close todo-pfj.1 --reason "Users table and migration merged"
bd ready1
2
3
4
5
6
7
8
9
✓ Closed todo-pfj.1 — Create users table and migration: Users table and migration merged
○ todo-pfj P1 [epic] User login
○ todo-pfj.2 P1 Add POST /login endpoint ← User login
○ todo-dgm P2 Specialize build-and-test for this repo
○ todo-27u P2 [bug] Todo list does not refresh after delete
--------------------------------------------------------------------------------
Ready: 4 issues with no active blockers
...todo-pfj.2 tự chuyển thành ready vì bead chặn nó đã đóng. Mở lại bdtui, chọn nó, bấm w rồi Enter lần nữa:

Trong pane Detail, todo-pfj.1 giờ có dấu ✓, còn status bar báo Copied: /executor-task todo-pfj.2. Quy trình hằng ngày của bạn chỉ có vậy: mở bdtui, chọn một bead ready, w, dán vào agent, review PR.
7. Lưu ý khi dùng thật
- Dolt chạy nền theo từng repo. Vì Beads ở server mode, mỗi repo có một process
doltriêng. Muốn tắt, chạybd dolt stoptrong repo đó. - Bead chỉ nằm trên máy bạn. Output của
bootstrapcó dòng cảnh báoNo Dolt remote configured, nghĩa là code được sync qua Git còn bead thì không. Muốn dùng trên máy khác, xem hướng dẫn sync. - Đừng sửa tay các skill dùng chung.
agent-workflow-beads update <repo>ghi đè chúng bằng bản mới. Skill duy nhất bạn nên chỉnh làbuild-and-test, vì lệnhupdategiữ nguyên bản bạn đã sửa. - Trên Windows, các skill chạy cả epic cần Git Bash.
/executor-epic-sequentialvà các skill cùng họ dùng shell kiểu POSIX, nên máy bạn phải có Git Bash (đi kèm Git for Windows). - Danh sách trong bdtui không tự cập nhật theo mặc định. Bấm
rđể tải lại. Status bar có gợi ýL enable live. BấmShift+lthì bdtui bật events journal của Beads (tương đươngbd config set events-journal true) và từ đó tự tải lại khi agent thay đổi bead.
Tóm lại, Beads giữ trạng thái công việc, agent-workflow-beads dạy agent làm từng bead một, còn bdtui giúp bạn nhìn thấy toàn cảnh. Trong thực tế, bạn nên bắt đầu thật nhỏ: bootstrap một repo cá nhân, dùng /plan-beads cho một tính năng vừa phải, rồi mở bdtui xem agent đi qua từng bead. Khi đã quen nhịp plan → làm → review, bạn có thể bỏ hẳn file TODO.md.