Plannotator: duyệt plan, tài liệu và code cùng AI agent chỉ với một cú nhấp — 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 plan, tài liệu, HTML hay code do AI agent tạo ra, rồi gửi phản hồi lại cho agent. Cài bằng một dòng lệnh duy nhất, sau đó làm thêm một bước nhỏ tuỳ agent bạn dùng. Với người đã quen terminal, cài đặt khá dễ.
Plannotator là một công cụ chạy cục bộ trên máy bạn, mở giao diện duyệt trong trình duyệt để bạn đọc, ghi chú và phản hồi những gì AI coding agent đưa ra: kế hoạch, tài liệu, trang HTML, thay đổi code. Bạn đánh dấu ngay trên nội dung, bấm gửi, và phản hồi quay về đúng agent đang làm việc. Repo hiện có khoảng 10233 sao và 776 fork, giấy phép Apache-2.0, viết chủ yếu bằng TypeScript.
Vấn đề nó giải quyết rất quen thuộc. Khi giao việc cho AI agent, bạn thường phải đọc một đoạn plan dài trong cửa sổ terminal, rồi gõ lại "đoạn thứ ba sửa thế này, đoạn thứ năm bỏ đi". Làm vậy vừa mệt vừa dễ sót. Plannotator cho bạn bôi đen, bình luận, đề xuất sửa ngay trên văn bản, giống như bạn góp ý một file Google Docs, rồi gói tất cả gửi cho agent một lần.
Nó hợp với lập trình viên đang dùng Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness hoặc Pi. Điểm đáng giá nhất là một bộ cài lo gần hết các agent này, và mọi dữ liệu mặc định ở lại trên máy bạn.
backnotprop/plannotator
Plannotator mở trình duyệt để bạn đánh dấu plan, tài liệu, diff code rồi gửi phản hồi ngược lại cho AI agent như Claude Code, Codex, OpenCode, Pi.
I.Plannotator làm được gì
A.Duyệt plan và tài liệu
Khi agent đề xuất một plan, giao diện tự mở trong trình duyệt. Bạn chú thích từng đoạn, rồi gửi phản hồi để agent sửa. Với plan mode, bạn không cần gõ lệnh nào: README nói plan mode được nối vào qua hook của từng agent, nên cứ agent tạo plan là màn hình duyệt xuất hiện.
Bạn cũng có thể chủ động đưa vào một file Markdown, một thư mục, một đường link hoặc trang HTML để chú thích. Tin nhắn cuối cùng của agent cũng duyệt được.
B.Code review cho thay đổi cục bộ và PR
Bạn có thể xem các thay đổi chưa commit, hoặc một pull request trên GitHub, một merge request trên GitLab. Bạn bình luận trên diff, đề xuất sửa code, và các bình luận đó quay về agent. README ghi rõ công cụ hỗ trợ Git, GitButler, Jujutsu (jj), Perforce (p4), GitHub và GitLab.
C.Inbox: một hộp thư cho nhiều agent
Khi bạn chạy nhiều agent cùng lúc, mỗi agent có thể để lại câu hỏi, file hoặc bản review trong một cửa sổ chung. Bạn trả lời bằng một cú nhấp, chú thích file, bấm gửi khi rảnh. Không có phiên làm việc nào bị giữ chờ trong lúc đó, và câu trả lời quay về đúng phiên đã hỏi.
D.AI tích hợp sẵn
Bạn có thể hỏi AI về thứ đang duyệt, hoặc chạy AI review để nó đăng bình luận lên diff. Khi đó nội dung liên quan sẽ được gửi tới nhà cung cấp AI mà bạn cấu hình (xem phần quyền riêng tư bên dưới).
E.Chia sẻ với đồng đội
Bạn có thể chia sẻ plan qua link để đồng đội tự chú thích, rồi nhập phản hồi của họ và gửi lại agent. README ghi tính năng link này đang chuyển sang diện hỗ trợ cũ, hướng chính cho làm việc nhóm là Workspaces (sản phẩm lưu trữ riêng).
F.Duyệt ngay trong terminal
Có repo đi kèm tên Herdr Annotate để duyệt trong terminal, và Plannotator TUI chạy độc lập không cần Herdr. Hai thứ này nằm ngoài phạm vi bài, bạn xem README của chúng nếu cần.
II.Cần chuẩn bị gì
Tư liệu README nói những điều sau:
- Hệ điều hành: macOS, Linux, WSL dùng lệnh
curl; Windows dùng PowerShell. - Một hoặc nhiều agent đã cài sẵn trong danh sách được hỗ trợ. Công cụ tự dò agent nào bạn đang có.
- Gemini CLI cần phiên bản 0.36.0 trở lên.
- Claude Code bản 2.1.287 trở lên có chế độ không bắt Claude chờ: Claude kết thúc lượt, quyết định của bạn đến sau dưới dạng tin nhắn.
- Codex: README ghi hook
Stopcủa Codex còn thử nghiệm, trên Windows gốc bộ cài sẽ in hướng dẫn cài tay. - Duyệt PR GitHub/GitLab dùng CLI đã đăng nhập và Git remote của bạn.
README không nêu yêu cầu về GPU hay phiên bản Node/Python cho người dùng cuối. Bộ cài tải sẵn file chạy (binary) từ GitHub Releases, nên có vẻ bạn không phải cài môi trường lập trình riêng. Hãy xem thêm trang tài liệu cài đặt nếu cần chắc chắn.
Tuỳ tính năng, có thể cần tài khoản hoặc cấu hình của nhà cung cấp AI khi dùng Ask AI. README chưa nói chi tiết ở phần được cung cấp.
III.Cài đặt từng bước
- Chạy bộ càiDán một dòng lệnh vào terminal để cài file plannotator và tự cấu hình agent
- Làm bước riêng cho agentMỗi agent có một bước hoàn tất khác nhau (Claude Code, OpenCode, Pi…)
- Khởi động lại agentĐể plugin, hook và lệnh mới có hiệu lực
- Thử một lệnhMở Inbox hoặc duyệt một file để kiểm tra
A.Chạy bộ cài chính
Mở terminal. Trên macOS, Linux hoặc WSL, dán lệnh sau:
# macOS / Linux / WSL
curl -fsSL https://plannotator.ai/install.sh | bashTrên Windows, mở PowerShell (không phải cmd) và dán:
# Windows PowerShell
irm https://plannotator.ai/install.ps1 | iexBộ cài sẽ cài file plannotator, tự dò các agent bạn có, rồi cấu hình hook, skill và slash command cho từng agent. Nó tải file từ GitHub Releases. Bản cài đầy đủ còn có thể kết nối GitHub, npm và một thành phần tuỳ chọn tên sem. Danh sách đầy đủ nằm trong chính sách riêng tư của dự án.
Lệnh dạng "tải script về rồi chạy ngay" thực thi mã trên máy bạn. Nếu muốn yên tâm, hãy mở địa chỉ script trong trình duyệt đọc trước, hoặc xem hướng dẫn cài trong tài liệu chính thức rồi mới chạy.
B.Chỉ cài file chạy, không cấu hình gì thêm
Nếu bạn chỉ muốn file plannotator, không muốn bộ cài đụng vào cấu hình agent, thêm cờ --minimal. File sẽ nằm ở ~/.local/bin, và mọi skill, hook, slash command đều được bỏ qua:
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ờ. Chọn cách này nếu bạn thích tự kiểm soát từng thứ.
C.Hoàn tất bước riêng cho agent bạn dùng
Sau bộ cài, mỗi agent có thêm một bước nhỏ. Bạn chỉ làm đúng dòng của agent mình đang dùng.
Claude Code. Trong Claude Code gõ hai lệnh sau, rồi khởi động lại Claude Code:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotatorOpenCode. 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 lệnh sau. Sau đó khởi động Pi với --plan, hoặc bật tắt bằng /plannotator-plan-mode:
pi install npm:@plannotator/pi-extensionCopilot CLI. Chạy hai lệnh, khởi động lại, plan review bật khi vào plan mode (Shift+Tab):
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@plannotatorDroid. Chỉ có lệnh, chưa chặn được plan:
droid plugin marketplace add https://github.com/backnotprop/plannotator
droid plugin install plannotator@plannotatorCodex, Gemini CLI, Kiro CLI. README ghi là không cần làm gì thêm sau bộ cài. Với Kiro, thử kiro-cli chat --agent plannotator. Riêng Amp, DeepSeek Harness và T3 Code có bước khác, bạn xem bảng trong README hoặc tài liệu cài đặt.
D.Khởi động lại agent
Đây là chỗ người mới hay quên. Plugin và hook chỉ được nạp khi agent khởi động, nên sau khi cài hãy đóng agent rồi mở lại.
E.Cập nhật và gỡ cài
Để cập nhật, chạy lại bộ cài. Với Claude Code, nếu lệnh claude có trong PATH thì bộ cài cũng tự cập nhật plugin. Nếu không, README hướng dẫn chạy claude plugin marketplace update plannotator, rồi claude plugin update plannotator@plannotator, rồi khởi động lại.
Để gỡ cài, mặc định giữ lại plan, lịch sử, bản nháp và cài đặt của bạn:
plannotator uninstallThêm --purge nếu muốn xoá luôn dữ liệu cục bộ. Lệnh sẽ bắt bạn gõ chữ purge để xác nhận và dữ liệu không thể khôi phục. Có thể 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 nhanh nhất theo README là mở Inbox:
plannotator inboxNếu cài đúng, một cửa sổ trình duyệt mở ra làm hộp thư của bạn. Có thể kiểm tra thêm bằng lệnh liệt kê các phiên đang chạy:
plannotator sessionsCách thứ hai là thử duyệt một file Markdown ngay trong agent. Ví dụ trong Claude Code:
/plannotator-annotate README.mdNếu trình duyệt mở ra với nội dung file và bạn bôi đen được để bình luận, mọi thứ đã sẵn sàng. Nếu agent báo không biết lệnh /plannotator-annotate, khả năng cao là bạn chưa khởi động lại agent hoặc chưa làm bước riêng cho agent đó.
V.Dùng vào việc thật
A.Duyệt plan trước khi AI bắt tay viết code
Bạn là lập trình viên nhỏ lẻ, nhờ agent thêm tính năng giỏ hàng. Agent đưa ra plan năm bước. Thay vì đọc trong terminal rồi gõ lại ý kiến, bạn chỉ việc đợi giao diện Plannotator mở ra, bôi đen bước bạn không đồng ý và viết lý do, rồi bấm gửi. Agent nhận toàn bộ góp ý một lần và sửa plan. Không cần gõ lệnh nào vì plan mode đã nối sẵn qua hook.
Đọc plan trong terminal là đọc cho xong; chú thích trực tiếp lên plan mới là duyệt thật sự.
Ông T
B.Góp ý một tài liệu có sẵn
Bạn làm văn phòng, đã nhờ agent soạn một bản mô tả yêu cầu sản phẩm bằng Markdown. Chạy lệnh sau (trong agent của bạn) để mở file ra chú thích:
/plannotator-annotate README.mdThay README.md bằng tên file của bạn. Bạn cũng có thể trỏ vào cả thư mục (/plannotator-annotate src/) hoặc một đường link. Mỗi góp ý gắn đúng vào đoạn chữ, rồi gửi lại để agent chỉnh. README còn chỉ tới một mẫu tài liệu yêu cầu sản phẩm để bạn tập dùng.
C.Duyệt thay đổi code chưa commit
Agent vừa sửa xong ba file. Bạn muốn xem trước khi commit. Chạy:
/plannotator-reviewGiao diện hiện diff. Bạn bình luận dòng nào cần đổi, thậm chí đề xuất code thay thế, rồi gửi. Agent nhận bình luận và sửa tiếp. Nếu cần duyệt một pull request, thay bằng /plannotator-review <github-pr-url>, hoặc dùng đường link merge request cho GitLab.
D.Xem lại câu trả lời cuối của agent và quản lý nhiều agent
Bạn vừa nhận một câu trả lời dài từ agent và muốn phản hồi từng ý. Dùng /plannotator-last để mở tin nhắn cuối ra chú thích. Còn khi chạy vài agent cùng lúc, hãy mở plannotator inbox làm nơi duy nhất để trả lời câu hỏi của tất cả chúng. Agent không dùng plugin riêng được thì nối qua MCP bằng plannotator inbox mcp, và plannotator inbox --help là hướng dẫn cho agent đọc.
VI.Lỗi hay gặp và cách xử lý
A.Gõ lệnh slash nhưng agent không nhận
Thường là do chưa khởi động lại agent, hoặc chưa làm bước plugin riêng (Claude Code, Copilot CLI, Droid, OpenCode, Pi). Hãy làm đúng bước của agent bạn trong phần cài đặt, rồi mở lại agent.
B.Terminal báo không tìm thấy lệnh plannotator
Với cài tối giản, file nằm ở ~/.local/bin. Nếu thư mục này chưa nằm trong PATH, terminal sẽ không thấy lệnh. Mở một cửa sổ terminal mới sau khi cài, và kiểm tra PATH của bạn. Chưa có thông tin cụ thể thêm trong phần README được cung cấp.
C.Codex trên Windows gốc không tự bật plan review
README ghi hook của Codex còn thử nghiệm, bộ cài sẽ in các bước cài tay trên Windows gốc. Hãy đọc kỹ phần in ra và làm theo, hoặc dùng WSL, nơi README nói plan review bật tự động.
D.Muốn tắt kiểm tra mạng khi duyệt code cục bộ
Duyệt Git cục bộ có thể hỏi remote origin bằng git ls-remote để dò nhánh mặc định. Nó không gửi diff của bạn. Muốn tắt hẳn, dùng plannotator review --no-git-remote-check, hoặc biến PLANNOTATOR_GIT_REMOTE_CHECK=0, hoặc đặt { "gitRemoteCheck": false } trong ~/.plannotator/config.json.
E.Claude cứ đứng chờ hoặc bạn thích kiểu cũ
Từ Claude Code 2.1.287 trở lên, review không bắt Claude chờ. Nếu bạn muốn quay lại cách chờ truyền thống, đặt PLANNOTATOR_CLAUDE_MOD=0.
Link chia sẻ nhỏ chứa nội dung trong phần sau dấu # của URL, không được mã hoá. Ai có đủ link đều đọc được. Link lớn mã hoá bằng AES-256-GCM nhưng ai có link vẫn giải mã được, và chỉ lưu 7 ngày. Đừng chia sẻ plan chứa key, mật khẩu hay dữ liệu khách hàng. Có thể tắt hẳn chia sẻ bằng PLANNOTATOR_SHARE=disabled.
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, giao diện trực quan hơn nhiều so với gõ phản hồi trong terminal. Dữ liệu (plan, diff, ghi chú, lịch sử, cấu hình) mặc định ở lại máy bạn, và README khẳng định công cụ không thu thập số liệu sử dụng. Dự án vẫn được cập nhật trong vài tháng gần đây.
Giới hạn cần biết.
- Mỗi lần mở giao diện, app kiểm tra bản phát hành mới trên GitHub, và hiện README ghi chưa có cách tắt việc này. Không có nội dung của bạn bị gửi đi trong lần kiểm tra đó.
- Ask AI và review agent sẽ gửi nội dung bạn chọn tới nhà cung cấp AI bạn cấu hình. Annotate URL cũng đi qua dịch vụ Jina Reader theo mặc định cho trang công khai.
- Mức hỗ trợ giữa các agent không đều: Droid mới chỉ có lệnh, chưa chặn plan; Codex trên Windows gốc cần cài tay.
- Link chia sẻ mã nguồn mở đang chuyển sang diện hỗ trợ cũ. Workspaces là sản phẩm lưu trữ riêng và không theo mô hình lưu cục bộ.
- Cách dùng đòi hỏi bạn đã quen với một agent trong terminal. Nếu bạn chưa dùng AI coding agent bao giờ, công cụ này chưa giúp ích ngay.
Khi nào chọn cách khác. Nếu bạn chỉ cần xem diff đơn giản, giao diện của Git hoặc trang PR sẵn có là đủ. Nếu cần cộng tác nhóm lâu dài, hãy xem Workspaces thay vì dựa vào link chia sẻ cũ. Còn nếu bạn thường xuyên giao việc cho agent và hay phải sửa plan hoặc code của nó, Plannotator đáng thử vì nó biến bước duyệt từ việc gõ lại thành việc đánh dấu và bấm gửi.
Câu hỏi thường gặp
Plannotator có miễn phí không?
Repo mã nguồn mở dùng giấy phép Apache-2.0 và bạn cài về dùng cục bộ được. Riêng Workspaces là sản phẩm lưu trữ riêng; README chưa nêu giá. Chi phí của nhà cung cấp AI khi dùng Ask AI hay review agent là chuyện khác, chưa có thông tin trong tư liệu.
Cần GPU hoặc cấu hình mạnh không?
Tư liệu không nhắc yêu cầu GPU hay phần cứng riêng. Công cụ chạy cục bộ và mở giao diện trong trình duyệt. Phần AI chạy qua nhà cung cấp mà bạn cấu hình.
Chạy trên Windows được không?
Được. README có lệnh cài bằng PowerShell cho Windows, và bản cho macOS, Linux, WSL dùng curl. Riêng hook của Codex trên Windows gốc còn thử nghiệm, bộ cài sẽ in hướng dẫn cài tay.
Dữ liệu của tôi có an toàn không?
README nói không thu thập telemetry, và plan, diff, ghi chú, lịch sử, cấu hình mặc định ở lại trên máy. Dữ liệu chỉ rời máy khi bạn dùng tính năng cần mạng như annotate URL, Ask AI, review bằng agent hoặc chia sẻ link. App có kiểm tra bản mới trên GitHub, hiện chưa có tuỳ chọn tắt.
Plannotator hỗ trợ những agent nào?
Theo README: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness và Pi. Riêng Inbox còn dùng được với các trợ lý cá nhân như Grok Bot, Muse, Hermes, OpenClaw. Mức hỗ trợ giữa các agent không đồng đều.
Plannotator khác gì việc gõ phản hồi thẳng cho agent?
Thay vì gõ lại từng ý, bạn bôi đen và bình luận ngay trên plan, tài liệu hay diff, rồi gửi toàn bộ một lần. Nó cũng gom câu hỏi từ nhiều agent vào một Inbox. README không so sánh với công cụ cụ thể nào khác.
Gỡ cài đặt có để lại rác không?
Lệnh `plannotator uninstall` 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. Muốn xoá cả dữ liệu cục bộ thì thêm `--purge`, và bạn phải gõ chữ `purge` để xác nhận. Có thể dùng `--dry-run` để xem trước.


