Plannotator: duyệt plan, tài liệu và code của AI agent bằng trình duyệt — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về backnotprop/plannotator — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: Plannotator: duyệt plan và code của AI agent ngay trên trình duyệt — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Plannotator là công cụ chạy cục bộ, mở giao diện trong trình duyệt để bạn đọc, bình luận plan, tài liệu và code mà AI agent (Claude Code, Codex, OpenCode, Pi…) đưa ra, rồi gửi phản hồi trở lại agent. Cài bằng một dòng lệnh, nhưng bước nối với từng agent thì khác nhau nên bạn cần làm theo đúng agent mình dùng.
Plannotator là một công cụ chạy trên máy bạn, mở giao diện duyệt trong trình duyệt để bạn đọc, ghi chú, bình luận những thứ AI agent tạo ra (plan, tài liệu, thay đổi code) rồi gửi phản hồi ngược lại cho agent chỉ với một cú bấm. Nó hỗ trợ nhiều agent như Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness và Pi.
Vấn đề nó giải quyết rất đời thường. Khi giao việc cho agent, bạn thường phải đọc plan dài trong cửa sổ dòng lệnh rồi gõ lại phản hồi bằng chữ. Vừa khó đọc, vừa khó chỉ ra chính xác đoạn nào cần sửa. Với Plannotator, agent đưa plan ra, trình duyệt tự mở, bạn bôi đen đoạn cần sửa, viết nhận xét, bấm gửi. Agent nhận phản hồi và làm tiếp.
Ai nên dùng? Lập trình viên (kể cả người mới) đang dùng agent viết code, và cả người làm kinh doanh, văn phòng muốn góp ý cho tài liệu, đặc tả, bản yêu cầu sản phẩm do agent soạn. Điểm đáng giá nhất: mặc định mọi thứ nằm trên máy bạn, và README nói rõ là không thu thập telemetry hay số liệu sử dụng. Repo hiện có khoảng 10.233 sao và 776 fork, dùng giấy phép Apache-2.0, vẫn được cập nhật trong vài tháng gần đây.
backnotprop/plannotator
Plannotator mở một cửa sổ trình duyệt trên máy bạn để ghi chú plan, tài liệu, diff của AI agent rồi gửi phản hồi ngược lại cho agent chỉ với một cú bấm.
I.Plannotator làm được gì
A.Duyệt plan, tài liệu, tin nhắn của agent
Bạn có thể ghi chú trực tiếp lên plan, đặc tả, file markdown, HTML và tin nhắn của agent, rồi gửi phản hồi về cho agent xử lý. Lợi ích: thay vì nhắn «sửa đoạn thứ ba cho rõ hơn», bạn chỉ thẳng vào đoạn đó và viết nhận xét ngay tại chỗ.
B.Duyệt code (Code Review)
Bạn xem thay đổi chưa commit hoặc pull request từ xa, bình luận trên từng đoạn diff, thậm chí đề xuất code. Các bình luận này quay về agent. README ghi công cụ làm việc với Git, GitButler, Jujutsu (jj), Perforce (p4), GitHub và GitLab. Nghĩa là dù nhóm bạn dùng hệ thống nào trong số đó, bạn vẫn có một chỗ duyệt thống nhất.
C.Plan mode tự mở
Không cần gõ lệnh gì. Plan mode được nối qua hook của từng agent, nên mỗi lần agent tạo plan thì giao diện duyệt markdown tự mở ra. Bạn không phải nhớ bước thủ công.
D.Inbox: hộp thư chung cho nhiều agent
Inbox là một cửa sổ cục bộ nơi các agent để lại câu hỏi, file, bản duyệt có hướng dẫn trong lúc chúng vẫn làm việc tiếp. Bạn trả lời bằng một cú bấm, ghi chú một file, rồi bấm Gửi khi tiện. Không có phiên nào bị treo chờ bạn, và câu trả lời quay về đúng phiên đã hỏi. Hợp khi bạn chạy nhiều agent cùng lúc và không muốn canh từng cửa sổ.
E.AI tích hợp sẵn
Bạn có thể hỏi AI về nội dung đang duyệt, hoặc chạy duyệt bằng AI để nó đăng bình luận lên diff.
F.Herdr Annotate và chia sẻ
Nếu bạn làm việc trong terminal, có thêm plugin Herdr Annotate để ghi chú ngay trong terminal. Ngoài ra có chia sẻ bằng link để đồng nghiệp tự ghi chú, nhưng README cho biết tính năng link mã nguồn mở đang chuyển sang diện hỗ trợ cũ, còn Workspaces là hướng chính cho cộng tác nhóm (đây là sản phẩm lưu trữ riêng, tách khỏi app mã nguồn mở).
II.Cần chuẩn bị gì
Tư liệu nói rõ những điều sau:
- Hệ điều hành: macOS, Linux, WSL hoặc Windows (có lệnh cài riêng cho PowerShell).
- Một AI agent đã cài sẵn trong danh sách được hỗ trợ (Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness, Pi…). Plannotator là lớp duyệt cắm vào agent, không thay thế agent.
- Gemini CLI cần phiên bản 0.36.0 trở lên.
- Với Claude Code 2.1.287 trở lên, cách hoạt động mới: Claude kết thúc lượt và quyết định của bạn đến sau như một tin nhắn.
- Có
claudetrong PATH nếu muốn trình cài đặt tự cập nhật plugin Claude Code. - Cần kết nối mạng khi cài: trình cài tải file từ GitHub Releases, và có thể liên hệ GitHub, npm hoặc Ataraxy-Labs/sem tùy agent bạn chọn.
- Duyệt PR GitHub hay GitLab dùng CLI và Git remote đã đăng nhập sẵn của bạn.
README không nói về yêu cầu phần cứng hay GPU, nên mình không đưa ra con số nào.
III.Cài đặt từng bước
- Mở terminalDùng terminal (macOS/Linux/WSL) hoặc PowerShell (Windows)
- Chạy trình cài đặtMột lệnh cài binary plannotator và tự dò agent đã có
- Làm bước riêng cho agentVí dụ Claude Code cần thêm plugin rồi khởi động lại
- Khởi động lại agentĐể hook và lệnh mới có hiệu lực
- Thử một lệnhChạy plannotator sessions hoặc /plannotator-annotate để kiểm tra
A.Bước 1: Mở terminal đúng loại
Trên macOS, Linux hoặc WSL, mở Terminal. Trên Windows, mở PowerShell. Không cần cd vào thư mục nào đặc biệt cho bước cài này.
B.Bước 2: Chạy trình cài đặt
Một trình cài đặt phục vụ gần như mọi agent. Nó cài binary plannotator, tự dò agent bạn đã cài, và cấu hình hook, skill, lệnh gạch chéo cho từng agent.
Trên macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bashTrên Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iexCả hai lệnh đều tải script từ trang của dự án rồi chạy luôn. Nếu bạn muốn tự đọc script trước khi chạy thì hãy mở địa chỉ đó trong trình duyệt xem trước.
Muốn chỉ cài binary, bỏ qua mọi skill, hook, lệnh gạch chéo và cấu hình riêng từng agent? Thêm --minimal. Binary sẽ nằm ở ~/.local/bin:
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimalBạn cũng có thể đặt biến môi trường PLANNOTATOR_MINIMAL=1 thay cho cờ này.
C.Bước 3: Làm bước tiếp theo theo agent của bạn
Sau trình cài, mỗi agent có một bước cuối riêng. Đây là chỗ người mới hay bỏ sót nhất. Theo README:
Claude Code. Gõ lần lượt hai lệnh trong Claude Code, rồi khởi động lại Claude Code:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotatorCodex. Không cần làm gì thêm. Duyệt plan được bật tự động qua hook Stop thử nghiệm của Codex (macOS/Linux/WSL). Trên Windows gốc, hook của Codex còn là thử nghiệm và trình cài sẽ in ra hướng dẫn thủ công. Các skill $plannotator-review, $plannotator-annotate, $plannotator-last đi kèm.
Copilot CLI. Gõ hai lệnh rồi khởi động lại. Duyệt plan hoạt động ở plan mode (Shift+Tab):
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@plannotatorGemini CLI. Không cần làm gì thêm, hook, policy và lệnh gạch chéo được cấu hình tự động. Cần Gemini CLI 0.36.0+.
Kiro CLI. Không cần làm gì thêm. Skill và một agent mẫu được cài sẵn. README gợi ý thử:
kiro-cli chat --agent plannotatorOpenCode. Thêm dòng sau vào opencode.json rồi khởi động lại OpenCode:
"plugin": ["@plannotator/opencode@latest"]Lưu ý: đây là một dòng nằm trong file JSON có sẵn của bạn, hãy thêm vào đúng chỗ, đừng dán đè cả file.
Pi. Bỏ qua trình cài, chỉ cần chạy lệnh sau. Rồi khởi động Pi với --plan, hoặc bật tắt bằng /plannotator-plan-mode:
pi install npm:@plannotator/pi-extensionDroid. Chạy hai lệnh. Droid hiện chỉ có lệnh, chưa chặn được plan:
droid plugin marketplace add https://github.com/backnotprop/plannotator
droid plugin install plannotator@plannotatorAmp, DeepSeek Harness, T3 Code. README có hướng dẫn riêng cho từng agent này (sao chép file plannotator.ts vào thư mục plugin của Amp rồi plugins: reload; thêm @plannotator/dsh trên trang Plugins của DSH; với T3 chạy plannotator t3 --help và làm theo hai bước). Vì các bước này dài hơn, bạn xem bảng cài đặt trong README hoặc trang tài liệu cài đặt của dự án.
D.Bước 4: Khởi động lại agent và cập nhật về sau
Sau khi cài plugin, hãy tắt agent và mở lại để hook có hiệu lực. Về sau, muốn cập nhật thì chạy lại trình cài đặt. Nếu bạn dùng plugin Claude Code mà muốn cập nhật thủ công, README ghi ba lệnh theo thứ tự (làm mới marketplace thôi là chưa đủ):
claude plugin marketplace update plannotator
claude plugin update plannotator@plannotatorSau đó khởi động lại Claude Code. Với Pi thì dùng pi update --extensions.
Trình cài đặt chạy bằng cách tải script từ mạng rồi thực thi ngay trên máy bạn. Chỉ làm vậy với nguồn bạn tin tưởng. Nếu muốn ít can thiệp nhất, dùng --minimal để chỉ cài binary.
IV.Kiểm tra đã chạy được chưa
Cách nhanh nhất là chạy lệnh liệt kê phiên hoạt động của Plannotator trong terminal:
plannotator sessionsNếu lệnh được nhận ra (không báo «command not found»), binary đã cài và nằm trong PATH. Tiếp theo, thử kiểm tra thật trong agent của bạn:
- Mở agent (ví dụ Claude Code) trong một thư mục có file markdown bất kỳ.
- Gõ
/plannotator-annotate README.md(Codex thì dùng!plannotator annotatehoặc skill$plannotator-annotate; hãy đổi tên file cho khớp). - Trình duyệt sẽ mở giao diện ghi chú. Thấy giao diện hiện ra là bạn đã cài thành công.
Với plan mode, kiểm tra bằng cách yêu cầu agent lập kế hoạch cho một việc nhỏ. Khi plan xong, giao diện duyệt markdown sẽ tự mở. README chưa nêu một dòng thông báo cụ thể nào để bạn đối chiếu, nên mốc kiểm tra là: trình duyệt tự mở ra.
V.Dùng vào việc thật
A.Người mới viết code: duyệt plan trước khi agent động vào file
Bạn nhờ agent thêm một tính năng nhỏ vào dự án. Thay vì để nó làm ngay, bạn bật plan mode. Plan được tạo ra, trình duyệt mở lên, bạn đọc từng bước, bôi đen bước nào bạn không muốn (ví dụ «đừng đổi cấu trúc thư mục») và viết nhận xét. Bấm gửi. Agent nhận phản hồi, sửa plan, rồi mới bắt tay làm. Kết quả: bạn kiểm soát hướng đi mà không phải gõ dài dòng trong terminal.
Đọc plan trong terminal là đọc cho xong; bôi đen đúng chỗ sai rồi gửi đi mới là duyệt thật.
Ông T
B.Nhân viên văn phòng: góp ý bản yêu cầu sản phẩm do agent soạn
Trưởng nhóm nhờ agent viết bản yêu cầu sản phẩm (PRD) dạng markdown. Bạn không cần biết code, chỉ cần mở file trong trình duyệt bằng lệnh mà dev trong nhóm cấu hình sẵn:
/plannotator-annotate README.mdĐổi tên file cho đúng với tài liệu của bạn. Bạn gắn bình luận «mục tiêu này chưa đo được» ở đoạn cần sửa, rồi gửi lại cho agent viết lại. README cũng gợi ý một mẫu PRD để bạn thử: một bản template và ví dụ điền sẵn có thể sao chép dạng Markdown để làm tài liệu thực hành.
Bạn cũng có thể đưa vào một địa chỉ web hoặc cả thư mục:
/plannotator-annotate src/
/plannotator-annotate https://docs.rs/…Với file HTML, thêm --render-html nếu muốn hiển thị nguyên trạng thay vì chuyển đổi:
/plannotator-annotate report.html --render-htmlC.Lập trình viên: duyệt thay đổi chưa commit hoặc một pull request
Agent vừa sửa xong vài file. Bạn muốn xem diff có ổn không trước khi commit:
/plannotator-reviewGiao diện duyệt mở ra, bạn bình luận từng dòng, có thể đề xuất code thay thế rồi gửi lại cho agent sửa tiếp. Muốn duyệt PR của đồng nghiệp thì đưa đường dẫn:
/plannotator-review <github-pr-url>
/plannotator-review <gitlab-mr-url>Người dùng GitButler có plannotator review --gitbutler, còn một file diff tĩnh thì dùng plannotator review --patch-file reading.diff. Kết quả: các góp ý tập trung ở một chỗ, đi thẳng về agent.
D.Người chạy nhiều agent: gom câu hỏi vào Inbox
Bạn giao ba việc cho ba agent và không muốn nhảy qua lại giữa ba cửa sổ. Chạy:
plannotator inboxCác agent để lại câu hỏi và file cần duyệt trong cùng một cửa sổ. Bạn trả lời từng việc khi rảnh, agent vẫn tiếp tục công việc khác trong lúc chờ. Claude Code, Pi và OpenCode nối qua plugin của Plannotator. Agent khác nối qua MCP bằng plannotator inbox mcp, và plannotator inbox --help là tài liệu để agent tự đọc.
Ngoài ra, lệnh /plannotator-last cho phép bạn ghi chú ngay tin nhắn cuối cùng của agent, rất tiện khi câu trả lời dài mà bạn chỉ muốn sửa một ý.
VI.Lỗi hay gặp và cách xử lý
A.Gõ plannotator báo không tìm thấy lệnh
Thường do terminal đang mở từ trước khi cài nên chưa nhận PATH mới. Đóng terminal rồi mở lại. Nếu bạn cài bằng --minimal, binary nằm ở ~/.local/bin, hãy kiểm tra thư mục này có trong PATH chưa. Trên Windows, README nói lệnh gỡ cài đặt có thể phải sửa PATH thủ công khi gặp sự cố, nên nếu bạn từng gỡ rồi cài lại, hãy kiểm tra PATH.
B.Gõ /plannotator-... mà agent không nhận
Hầu hết là do chưa khởi động lại agent sau khi cài plugin. Với Claude Code, hãy chắc rằng bạn đã chạy cả hai lệnh /plugin marketplace add và /plugin install, rồi thoát ra mở lại. Nếu vừa cập nhật, nhớ rằng làm mới marketplace thôi chưa đủ, phải chạy thêm lệnh cập nhật plugin.
C.Codex trên Windows không tự mở giao diện duyệt plan
README ghi rõ: trên Windows gốc, hook của Codex còn thử nghiệm và trình cài chỉ in hướng dẫn thủ công. Bạn làm theo các bước nó in ra, hoặc dùng WSL, nơi duyệt plan được bật tự động. Trong lúc chờ, lệnh !plannotator review và các skill $plannotator-* vẫn là lối đi thay thế.
D.Agent đứng chờ hoặc hành vi khác với bạn tưởng
Với Claude Code 2.1.287 trở lên, cách mới là Claude kết thúc lượt và quyết định của bạn đến sau như một tin nhắn. Nếu bạn quen kiểu chờ cũ, đặt biến môi trường PLANNOTATOR_CLAUDE_MOD=0 để quay về luồng cổ điển.
E.Chia sẻ link xong, người nhận không mở được hoặc lo lộ nội dung
Link chia sẻ bản lớn và HTML dùng dịch vụ rút gọn có mã hoá, bản lưu trên máy chủ hết hạn sau 7 ngày. Bản nhỏ được nén vào phần fragment của URL, không mã hoá, nên ai có đủ link đều đọc được. Đừng gửi link chứa thông tin nhạy cảm vào kênh bạn không tin. Muốn tắt hẳn chia sẻ thì đặt PLANNOTATOR_SHARE=disabled.
Mặc định dữ liệu ở lại máy bạn, nhưng một số tính năng đưa nội dung ra ngoài: ghi chú URL (qua Jina Reader), Ask AI và duyệt bằng AI (gửi nội dung đến nhà cung cấp AI bạn cấu hình), và chia sẻ link. Dùng những tính năng này với tài liệu nhạy cảm thì hãy cân nhắc trước.
VII.Có nên dùng không
Điểm mạnh. Nhiều agent dùng chung một giao diện duyệt. Mặc định chạy cục bộ, không thu thập telemetry. Hỗ trợ duyệt plan, tài liệu, diff và PR trong một công cụ, với nhiều hệ quản lý mã nguồn. Giấy phép Apache-2.0, vẫn đang được cập nhật.
Giới hạn cần biết.
- Mỗi lần mở giao diện đều kiểm tra GitHub để xem có bản mới không. README nói chưa có tuỳ chọn tắt việc này (việc kiểm tra không gửi nội dung plan hay review).
- Với duyệt code trên Git cục bộ, công cụ có thể hỏi
originbằnggit ls-remote. Bạn tắt được bằngplannotator review --no-git-remote-check, biếnPLANNOTATOR_GIT_REMOTE_CHECK=0, hoặc{ "gitRemoteCheck": false }trong~/.plannotator/config.json. - Cách nối với mỗi agent khác nhau và một số còn thử nghiệm (Codex trên Windows gốc, Droid chưa chặn được plan).
- Chia sẻ link mã nguồn mở đang chuyển sang diện hỗ trợ cũ; cộng tác nhóm lâu dài hướng tới Workspaces, một sản phẩm lưu trữ riêng.
- README được cung cấp bị cắt giữa chừng, nên mình không có thông tin về một số phần như cấu hình nâng cao.
Khi nào chọn cách khác. Nếu bạn chỉ làm việc một mình với tài liệu ngắn và không dùng agent, một trình soạn thảo thường là đủ. Nếu bạn chưa dùng AI agent nào, hãy cài một agent trước rồi quay lại thêm Plannotator. Nếu nhóm bạn cần một nơi lưu trữ và cộng tác chung lâu dài, hãy tìm hiểu Workspaces của dự án hoặc công cụ duyệt code đang dùng sẵn trong công ty. Còn nếu bạn muốn kiểm soát từng quyết định của agent mà không phải đọc tường chữ trong terminal, Plannotator rất đáng thử.
Câu hỏi thường gặp
Plannotator có miễn phí không?
Repo là mã nguồn mở với giấy phép Apache-2.0. README không nêu phí cho app mã nguồn mở. Workspaces được mô tả là một sản phẩm lưu trữ riêng, và mình chưa có thông tin về giá của nó.
Plannotator chạy được trên Windows không?
Được. README có lệnh cài riêng cho Windows PowerShell, còn macOS, Linux và WSL dùng lệnh curl. Riêng Codex trên Windows gốc thì hook còn thử nghiệm, trình cài sẽ in hướng dẫn thủ công.
Dữ liệu của mình có an toàn không?
Theo README, plan, diff, ghi chú, bản nháp và cấu hình ở lại máy bạn theo mặc định, và công cụ không thu thập telemetry. Nội dung chỉ ra ngoài khi bạn dùng tính năng cần mạng như ghi chú URL, Ask AI hay chia sẻ link.
Plannotator hỗ trợ những agent nào?
README liệt kê Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness và Pi. Inbox còn dùng được với một số trợ lý cá nhân như Grok Bot, Muse, Hermes, OpenClaw.
Cần GPU hay cấu hình máy mạnh không?
README không nêu yêu cầu phần cứng hay GPU. Công cụ là giao diện duyệt chạy trong trình duyệt, còn phần nặng nằm ở agent bạn dùng.
Làm sao gỡ Plannotator?
Chạy plannotator uninstall. Mặc định lệnh này gỡ các thành phần mà Plannotator đã cài và giữ lại plan, lịch sử, bản nháp, cài đặt của bạn. Thêm --purge để xoá cả dữ liệu cục bộ; lệnh sẽ yêu cầu bạn gõ purge để xác nhận.
Link chia sẻ có bị lộ nội dung không?
Bản markdown nhỏ được nén trong phần fragment của URL và không mã hoá, nên ai có đủ link đều đọc được. Bản lớn và HTML được mã hoá AES-256-GCM trước khi tải lên, máy chủ chỉ giữ bản mã và bản lưu hết hạn sau 7 ngày. Bạn có thể tắt chia sẻ bằng PLANNOTATOR_SHARE=disabled.


