Plannotator: duyệt kế hoạch và code của AI agent — 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 trên máy bạn, mở một giao diện trong trình duyệt để bạn đọc, ghi chú và duyệt kế hoạch, tài liệu, thay đổi code mà AI agent đưa ra, rồi gửi phản hồi ngược lại cho agent. Nó hỗ trợ nhiều agent như Claude Code, Codex, Gemini CLI, OpenCode, Pi. Cài đặt chỉ cần một dòng lệnh, sau đó thêm một bước nhỏ tuỳ agent bạn dùng.
Plannotator là một công cụ chạy cục bộ, mở trong trình duyệt, giúp bạn duyệt những gì AI agent đưa ra: kế hoạch, tài liệu, file HTML, thay đổi code. Bạn bôi đen, bình luận, rồi gửi phản hồi thẳng cho agent để nó sửa tiếp. Hiện repo có khoảng 10.210 sao và 773 fork, giấy phép Apache-2.0.
Vấn đề nó giải quyết rất đời thường. Khi agent như Claude Code đưa ra một bản kế hoạch dài, bạn thường phải trả lời bằng cách gõ tay trong terminal: "sửa mục 3, bỏ mục 5…". Rất khó chỉ đúng chỗ. Với Plannotator, bản kế hoạch hiện ra như một trang tài liệu, bạn chọn đúng đoạn cần sửa, ghi chú ngay tại đó rồi bấm gửi.
Bạn nên dùng nếu đang làm việc với một hoặc nhiều AI coding agent và muốn kiểm soát chúng tốt hơn, dù là lập trình viên mới hay người làm kinh doanh tự dựng công cụ nhỏ bằng agent. Điểm đáng giá nhất: một bộ cài phủ gần hết các agent phổ biến, và theo README, kế hoạch, bản diff, ghi chú mặc định đều nằm trên máy bạn.
backnotprop/plannotator
Plannotator mở trình duyệt cục bộ để bạn ghi chú kế hoạch, duyệt code và gửi phản hồi thẳng cho AI agent như Claude Code, Codex, OpenCode chỉ với một cú bấm.
I.Plannotator làm được gì
A.Duyệt kế hoạch, tài liệu và tin nhắn của agent
Khi agent đề xuất một kế hoạch hoặc quyết định, trình duyệt tự mở ra để bạn đánh dấu và bình luận. Bạn cũng có thể tự mở một file Markdown, một thư mục, một địa chỉ web hay file HTML để ghi chú. Lợi ích: phản hồi chính xác từng đoạn thay vì mô tả mơ hồ bằng lời.
B.Duyệt code (code review)
Bạn xem thay đổi chưa commit hoặc một pull request từ xa, bình luận trên từng dòng diff, thậm chí gợi ý code. Bình luận của bạn quay về agent. README nói công cụ làm việc với Git, GitButler, Jujutsu (jj), Perforce (p4), GitHub và GitLab.
C.Hộp thư Inbox
Inbox là một cửa sổ cục bộ nơi các agent để lại tin nhắn, câu hỏi, file hoặc bài review có hướng dẫn trong khi chúng vẫn làm việc. Bạn trả lời bằng một cú bấm, và câu trả lời quay về đúng phiên đã hỏi. Phù hợp khi bạn chạy nhiều agent cùng lúc.
D.Hỏi AI ngay khi đang duyệt
Bạn có thể hỏi AI về thứ đang xem, hoặc chạy review bằng AI để nó đăng bình luận lên diff. Nội dung liên quan sẽ được gửi đến nhà cung cấp AI bạn đã cấu hình.
E.Chia sẻ cho đồng nghiệp
Bạn gửi link để người khác tự ghi chú, rồi nhập phản hồi của họ gửi lại cho agent. README cho biết kiểu chia sẻ bằng link này đang chuyển sang diện hỗ trợ cũ, còn hướng chính cho làm việc nhóm là Workspaces, một sản phẩm lưu trữ riêng.
F.Dùng trong terminal
Có thêm Herdr Annotate để ghi chú ngay trong terminal Herdr, và Plannotator TUI chạy độc lập không cần Herdr.
II.Cần chuẩn bị gì
Tư liệu chỉ nói những điều sau:
- Hệ điều hành: macOS, Linux, WSL hoặc Windows (PowerShell).
- Ít nhất một AI agent đã cài sẵn, ví dụ Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness hoặc Pi.
- Gemini CLI cần phiên bản 0.36.0 trở lên.
- Plan review của Codex dựa trên hook
Stopthử nghiệm. README ghi hỗ trợ trên macOS/Linux/WSL; trên Windows gốc, trình cài đặt sẽ in ra các bước cài tay. - Một trình duyệt để mở giao diện.
README không nói cần GPU hay tài khoản trả phí nào để chạy chính Plannotator. Riêng tính năng Ask AI thì dùng nhà cung cấp AI bạn tự cấu hình.
III.Cài đặt từng bước
- Chạy bộ càiMột dòng lệnh cài chương trình plannotator và tự nhận diện agent của bạn
- Làm bước riêng cho agentTuỳ agent: Claude Code, OpenCode, Pi cần thêm một bước
- Khởi động lại agentĐể plugin và hook có hiệu lực
- Thử một lệnhMở thử annotate hoặc review để xem trình duyệt bật lên
A.Bước 1: Chạy bộ cài
Mở terminal (macOS/Linux/WSL) hoặc PowerShell (Windows). Bộ cài tải chương trình plannotator từ GitHub Releases, tự tìm các agent đã cài trên máy và cấu hình hook, skill, lệnh gạch chéo cho từng cái.
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bashWindows PowerShell:
irm https://plannotator.ai/install.ps1 | iexBạn đang chạy một script tải từ mạng, nên hãy chắc chắn gõ đúng địa chỉ. Nếu chỉ muốn cái chương trình, không muốn bộ cài đụng vào cấu hình agent, dùng bản tối giản. Bản này chỉ cài file plannotator vào ~/.local/bin:
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimalB.Bước 2: Làm thêm bước riêng cho agent của bạn
Dưới đây là các bước đúng theo README.
Claude Code — gõ trong Claude Code:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotatorSau đó khởi động lại Claude Code.
Copilot CLI:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@plannotatorKhởi động lại; plan review bật khi ở chế độ plan (Shift+Tab).
OpenCode — thêm dòng sau vào file opencode.json rồi khởi động lại OpenCode:
"plugin": ["@plannotator/opencode@latest"]Pi — bỏ qua bộ cài, chạy:
pi install npm:@plannotator/pi-extensionRồi chạy Pi với --plan, hoặc bật tắt bằng /plannotator-plan-mode.
Droid:
droid plugin marketplace add https://github.com/backnotprop/plannotator
droid plugin install plannotator@plannotatorVới Droid, README ghi hiện chỉ có lệnh, chưa chặn được plan.
Codex, Gemini CLI, Kiro CLI: README ghi "Nothing", nghĩa là bộ cài đã cấu hình xong, không cần làm gì thêm. Với Kiro, thử kiro-cli chat --agent plannotator.
Amp, DeepSeek Harness, T3 Code: các bước có khác (ví dụ Amp phải chép file plannotator.ts vào ~/.config/amp/plugins/). Bạn xem bảng "Install" trong README của repo cho chính xác.
C.Bước 3: Cập nhật về sau
Chạy lại bộ cài ở Bước 1 để cập nhật chương trình và lệnh gạch chéo. README nói bộ cài cũng cập nhật plugin Claude Code nếu lệnh claude có trong PATH. Nếu không, chạy:
claude plugin marketplace update plannotator
claude plugin update plannotator@plannotatorRồi khởi động lại Claude Code. Với Pi: pi update --extensions.
D.Gỡ cài đặt
Mặc định gỡ các thành phần đã cài nhưng giữ lại kế hoạch, lịch sử, bản nháp và cài đặt của bạn:
plannotator uninstallMuốn xoá luôn dữ liệu cục bộ thì thêm --purge. Lệnh sẽ bắt bạn gõ chữ purge để xác nhận, và dữ liệu đó không khôi phục được. Thêm --dry-run để xem trước mà chưa xoá gì.
plannotator uninstall --purgeIV.Kiểm tra đã chạy được chưa
Cách đơn giản nhất là mở thử một thứ gì đó. README liệt kê các lệnh sau, trong đó lệnh gạch chéo gõ bên trong agent:
/plannotator-annotate README.mdNếu cài đúng, một tab trình duyệt sẽ mở ra hiển thị file đó để bạn ghi chú. Trên Codex, thay lệnh gạch chéo bằng !plannotator … (ví dụ !plannotator review) hoặc các skill $plannotator-*.
Bạn cũng có thể kiểm tra riêng chương trình bằng lệnh có trong README:
plannotator sessionsLệnh này liệt kê các phiên Plannotator đang chạy. Nếu máy báo không tìm thấy lệnh plannotator, xem phần lỗi thường gặp bên dưới.
V.Dùng vào việc thật
A.Duyệt kế hoạch trước khi agent bắt tay làm
Bối cảnh: bạn là chủ shop nhỏ, nhờ agent làm một trang quản lý đơn hàng. Agent đưa ra bản kế hoạch gồm nhiều mục. Với plan mode, bạn không cần gõ lệnh nào; README nói plan mode được nối qua hook của từng agent, mỗi khi agent tạo kế hoạch thì giao diện duyệt Markdown tự mở. Bạn bôi đen mục không cần, ghi chú "bỏ phần này, làm sau", rồi gửi. Agent nhận phản hồi và chỉnh lại kế hoạch.
Đọc kế hoạch như đọc một trang tài liệu, rồi chỉ thẳng vào chỗ sai, nhanh hơn nhiều so với gõ mô tả trong terminal.
Ông T
B.Ghi chú một tài liệu có sẵn
Bối cảnh: nhân viên văn phòng có file bao-cao.md hoặc một trang web cần góp ý. Bạn gõ trong agent:
/plannotator-annotate README.md
/plannotator-annotate https://docs.rs/…
/plannotator-annotate report.html --render-htmlDòng đầu mở file Markdown cục bộ, dòng hai tải và ghi chú một địa chỉ web, dòng ba hiển thị HTML nguyên bản thay vì chuyển đổi. Bạn ghi chú xong thì gửi về agent để nó sửa nội dung. Muốn duyệt câu trả lời gần nhất của agent, dùng /plannotator-last.
C.Duyệt code agent vừa viết
Bối cảnh: lập trình viên mới nhờ agent sửa lỗi, muốn xem kỹ trước khi commit. Bạn gõ:
/plannotator-reviewLệnh này mở các thay đổi chưa commit để bạn bình luận từng dòng. Muốn duyệt một pull request, dán địa chỉ PR (hoặc merge request của GitLab) sau lệnh:
/plannotator-review <github-pr-url>Bình luận của bạn quay về agent để nó sửa tiếp.
D.Quản lý nhiều agent bằng Inbox
Bối cảnh: bạn cho vài agent chạy song song và không muốn canh từng cửa sổ. Mở Inbox bằng:
plannotator inboxAgent để lại câu hỏi hoặc file, bạn trả lời bằng một cú bấm, câu trả lời về đúng phiên đã hỏi. Claude Code, Pi và OpenCode kết nối qua plugin. Agent khác kết nối qua MCP bằng plannotator inbox mcp, còn plannotator inbox --help là hướng dẫn để chính agent đọc.
Ask AI và các agent review sẽ gửi câu hỏi cùng nội dung plan, tài liệu hoặc diff liên quan đến nhà cung cấp AI bạn đã cấu hình. Đừng đưa tài liệu nhạy cảm vào nếu chưa hiểu nơi nó được gửi đến. Link chia sẻ nhỏ thì nội dung nằm trong chính đường link, ai có đủ link đều đọc được.
VI.Lỗi hay gặp và cách xử lý
A.Gõ plannotator báo không tìm thấy lệnh
Chương trình có thể chưa nằm trong PATH. Mở terminal mới sau khi cài rồi thử lại. Nếu dùng bản --minimal, file nằm ở ~/.local/bin, hãy kiểm tra thư mục này có trong PATH không.
B.Cài plugin Claude Code xong mà không thấy lệnh /plannotator-…
Bạn chưa khởi động lại Claude Code. README nhấn mạnh phải restart. Khi cập nhật, chỉ làm mới marketplace là chưa đủ, phải chạy tiếp lệnh claude plugin update plannotator@plannotator.
C.Codex trên Windows không tự hiện giao diện duyệt plan
Hook của Codex còn đang thử nghiệm. Trên Windows gốc, bộ cài chỉ in ra các bước cài tay. Bạn làm theo các bước đó, hoặc dùng WSL như README gợi ý cho nhóm macOS/Linux/WSL.
D.Bộ cài không gỡ được binary khi uninstall
Theo README, nếu một file cấu hình agent không đọc được, hoặc có hook do bạn tự thêm vẫn gọi Plannotator, lệnh gỡ sẽ giữ lại binary và báo tên file cùng cách xử lý. Làm theo hướng dẫn trong thông báo rồi chạy lại lệnh gỡ. Bạn có thể thêm --dry-run để xem trước.
E.Nghi ngờ mạng bị gọi ra ngoài khi duyệt code
README giải thích đây là hành vi có chủ đích: duyệt Git cục bộ có thể gọi git ls-remote đến origin để dò nhánh mặc định, và không gửi diff của bạn. Muốn tắt hẳn, dùng plannotator review --no-git-remote-check, biến môi trường PLANNOTATOR_GIT_REMOTE_CHECK=0, hoặc { "gitRemoteCheck": false } trong ~/.plannotator/config.json.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một dòng lệnh. Hỗ trợ rất nhiều agent. Đúng theo README, dự án không thu thập telemetry hay số liệu sử dụng, và kế hoạch, diff, ghi chú, lịch sử mặc định nằm trên máy bạn. Nó cũng hợp với cách làm việc kiểu "giao việc rồi duyệt" thay vì ngồi canh agent.
Giới hạn. Mỗi lần mở giao diện, ứng dụng kiểm tra bản phát hành mới trên GitHub, và README ghi hiện chưa có tuỳ chọn tắt việc này. Các tính năng như đọc URL, Ask AI, duyệt GitHub/GitLab hay chia sẻ đều gửi dữ liệu ra ngoài khi bạn dùng. Chia sẻ bằng link mã nguồn mở đang chuyển sang diện hỗ trợ cũ. Mức hỗ trợ giữa các agent không đều: Droid hiện chỉ có lệnh, chưa chặn plan.
Khi nào chọn cách khác. Nếu bạn chỉ thỉnh thoảng đọc một kế hoạch ngắn, gõ trả lời trực tiếp trong agent là đủ. Nếu cần cộng tác nhóm có lưu trữ trên máy chủ, README chỉ về Workspaces, một sản phẩm riêng có hosted, nên mô hình lưu cục bộ của bản mã nguồn mở không áp dụng ở đó. Muốn hiểu chi tiết từng agent, hãy đọc tài liệu cài đặt trên trang chủ dự án.
Câu hỏi thường gặp
Plannotator có miễn phí không?
Repo dùng giấy phép Apache-2.0 và có thể cài về chạy trên máy bạn. Tư liệu không nêu giá cho bản mã nguồn mở. Workspaces là một sản phẩm hosted riêng, README không nói về chi phí của nó.
Plannotator có cần GPU không?
README không đề cập yêu cầu GPU. Plannotator là giao diện review mở trong trình duyệt, còn việc chạy AI do agent bạn dùng (Claude Code, Codex…) đảm nhiệm.
Chạy trên Windows được không?
Được. README có lệnh cài riêng cho Windows PowerShell là irm https://plannotator.ai/install.ps1 | iex. Riêng Codex trên Windows gốc thì hook còn thử nghiệm và bộ cài chỉ in ra các bước cài tay.
Dữ liệu của tôi có an toàn không?
Theo README, Plannotator không thu thập telemetry, và kế hoạch, diff, ghi chú, bản nháp, lịch sử, cấu hình mặc định nằm trên máy bạn. Dữ liệu chỉ ra ngoài khi bạn dùng các tính năng cần mạng như đọc URL, Ask AI, duyệt GitHub/GitLab hay chia sẻ link.
Hỗ trợ những AI agent nào?
README liệt kê Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness và Pi. Riêng Inbox còn hoạt động với trợ lý cá nhân như Grok Bot, Muse, Hermes, OpenClaw.
Làm sao gỡ Plannotator?
Chạy plannotator uninstall để gỡ các thành phần đã cài nhưng giữ lại kế hoạch và cài đặt của bạn. Thêm --purge nếu muốn xoá cả dữ liệu cục bộ, lúc đó bạn phải gõ chữ purge để xác nhận. Có thể thêm --dry-run để xem trước.
Link chia sẻ kế hoạch có riêng tư không?
Với bản markdown nhỏ, nội dung nén trong phần fragment của URL và không được mã hoá, ai có đủ link đều đọc được. Bản lớn hoặc HTML thô dùng dịch vụ link ngắn, mã hoá AES-256-GCM trước khi tải lên và hết hạn sau 7 ngày. Bạn có thể tắt hẳn việc chia sẻ bằng PLANNOTATOR_SHARE=disabled.


