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 trên trình duyệt để bạn đọc, ghi chú plan, tài liệu, HTML hoặc diff code mà AI agent (Claude Code, Codex, OpenCode, Pi…) tạo ra, rồi gửi phản hồi ngược lại cho agent. Cài bằng một dòng lệnh, nhưng mỗi agent có thêm một bước hoàn tất riêng.
Plannotator là một giao diện duyệt chạy cục bộ trên trình duyệt, dành cho các AI coding agent như Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness và Pi. Khi agent đưa ra một kế hoạch, một tài liệu hay vừa sửa xong code, Plannotator mở ra để bạn đọc, bôi đen, bình luận, rồi gửi phản hồi về cho agent xử lý tiếp.
Vấn đề nó giải quyết rất quen thuộc. Agent làm nhanh, nhưng bạn khó chen vào đúng chỗ để chỉnh. Gõ chat dài dòng thì mệt, dễ sót ý. Với Plannotator, bạn chọn đúng đoạn cần sửa, ghi nhận xét ngay tại đó, và agent nhận được phản hồi có ngữ cảnh rõ ràng.
Repo này hợp với lập trình viên đang dùng agent hằng ngày, và cả người mới đang tập giao việc cho AI. Điểm đáng giá nhất là bạn duyệt được nhiều thứ trên cùng một nơi: plan, tài liệu Markdown, trang HTML, diff code, pull request. Repo hiện có khoảng 10.210 sao và 773 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong vài tháng gần đây.
backnotprop/plannotator
Plannotator mở một giao diện duyệt trên trình duyệt để bạn bình luận plan, tài liệu, diff và gửi phản hồi thẳng về AI coding agent chỉ với một cú bấm.
I.Plannotator làm được gì
A.Duyệt plan và tài liệu
Khi agent tạo plan, giao diện duyệt Markdown tự mở ra. Bạn không cần gõ lệnh nào, vì plan mode được nối qua hook của từng agent. Bạn đọc plan, ghi chú vào chỗ chưa ổn, rồi gửi lại. Agent sửa plan theo ý bạn thay vì tự đoá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 web hoặc một file HTML để ghi chú. Có lệnh riêng để duyệt tin nhắn cuối cùng của agent.
B.Duyệt code (Code Review)
Bạn xem thay đổi chưa commit, hoặc một pull request trên GitHub, merge request trên GitLab. Bạn bình luận lên từng dòng diff, thậm chí đề xuất code thay thế. Bình luận của bạn quay về cho agent. README nói công cụ làm việc đượ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 câu hỏi, file, bản duyệt có hướng dẫn trong lúc chúng vẫn đang làm việc. Bạn trả lời bằng một cú bấm, rồi bấm Send khi tiện. Không có phiên agent nào bị treo chờ bạn, và câu trả lời quay về đúng phiên đã hỏi. Với nhiều agent chạy song song, đây là chỗ giúp bạn không bị rối.
D.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 các lượt review bằng AI để chúng đăng bình luận lên diff. Phần này gửi nội dung liên quan tới nhà cung cấp AI bạn đã cấu hình (xem mục Có nên dùng không).
E.Chia sẻ cho đồng đội
Bạn gửi plan cho đồng nghiệp để họ tự ghi chú, rồi nhập phản hồi của họ và gửi lại cho agent. README ghi chức năng chia sẻ qua link mã nguồn mở đang dần chuyển sang diện không còn phát triển, và 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.Duyệt trong terminal
Tác giả có thêm Herdr Annotate để ghi chú ngay trong terminal. Hướng dẫn dưới đây chỉ tập trung vào bản chính.
II.Cần chuẩn bị gì
Theo README, bạn cần:
- Một hệ điều hành chạy được lệnh cài: macOS, Linux, WSL, hoặc Windows với PowerShell.
- Ít nhất một agent đã cài sẵn trên máy (ví dụ Claude Code, Codex, OpenCode, Pi…). Trình cài đặt tự dò agent bạn có.
- Gemini CLI phải là bản 0.36.0 trở lên nếu bạn dùng nó.
- Claude Code bản 2.1.287 trở lên để dùng kiểu «không bắt Claude chờ»: Claude kết thúc lượt, và quyết định của bạn đến sau dưới dạng một tin nhắn.
- Để duyệt pull request GitHub hoặc GitLab, README nói công cụ dùng CLI đã đăng nhập và Git remote của bạn.
README không nêu phiên bản Node hay Python tối thiểu, không yêu cầu GPU, và không nói cần API key riêng cho phần cài cơ bản. Cần key hay không phụ thuộc vào nhà cung cấp AI bạn cấu hình cho tính năng Ask AI, và tư liệu mình có chưa nói chi tiết.
Trình cài đặt tải file chạy từ GitHub Releases và có thể tải thêm từ GitHub, npm. Bạn nên đọc kỹ lệnh trước khi dán vào terminal, vì lệnh dạng «tải về rồi chạy ngay» sẽ thực thi script từ internet trên máy của bạn.
III.Cài đặt từng bước
- Mở terminalDùng terminal hoặc PowerShell phù hợp hệ điều hành
- Chạy trình càiMột lệnh cài file plannotator và tự cấu hình agent
- Hoàn tất theo agentLàm thêm bước riêng cho agent của bạn
- Khởi động lại agentĐể hook và lệnh mới có hiệu lực
- Thử một lệnhVí dụ mở Inbox hoặc duyệt một file
A.Mở terminal đúng chỗ
Trên macOS, Linux hoặc WSL, mở Terminal. Trên Windows, mở PowerShell. Bạn không cần đứng trong thư mục nào đặc biệt để chạy trình cài, nhưng khi dùng thật nên mở terminal ở thư mục dự án của bạn.
B.Chạy trình cài đặt
Một trình cài đặt phủ gần hết các agent. Nó cài file plannotator, tự dò agent đang có và cấu hình hook, skill, lệnh slash cho từng agent.
Trên macOS, Linux hoặc WSL:
curl -fsSL https://plannotator.ai/install.sh | bashTrên Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iexNếu bạn chỉ muốn file chạy mà không muốn nó đụng tới cấu hình agent, thêm --minimal. Khi đó file được đặt ở ~/.local/bin và mọi skill, hook, lệnh slash, cấu hình theo agent đều bị bỏ qua:
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimalBạn cũng có thể đặt biến PLANNOTATOR_MINIMAL=1 thay cho cờ này.
C.Hoàn tất theo từng agent
Sau trình cài, mỗi agent cần một bước riêng. Bạn chỉ làm bước của agent mình dùng.
Claude Code. Chạy hai lệnh trong Claude Code, rồi khởi động lại:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotatorCopilot CLI. Tương tự, rồi khởi động lại. Plan review bật trong plan mode (bấm Shift+Tab):
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@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 trình cài, chạy thẳng lệnh này. Sau đó chạy Pi với --plan, hoặc bật tắt bằng /plannotator-plan-mode:
pi install npm:@plannotator/pi-extensionDroid. 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 thêm gì, trình cài tự cấu hình. Với Codex trên Windows gốc, hook còn ở mức thử nghiệm và trình cài sẽ in ra các bước cài tay. Riêng Kiro, bạn thử bằng kiro-cli chat --agent plannotator.
Amp, DeepSeek Harness, T3 Code. README có hướng dẫn riêng (chép file plugin, thêm gói @plannotator/dsh, hoặc chạy plannotator t3 --help). Bạn xem bảng Install trong README của repo để làm đúng từng bước.
D.Khởi động lại agent
Chỗ người mới hay quên: sau khi cài plugin hoặc sửa cấu hình, bạn phải khởi động lại agent. Nếu chưa, lệnh /plannotator-... sẽ không xuất hiện.
E.Cập nhật và gỡ cài
Để cập nhật, chạy lại trình cài. Nếu có Claude Code trong PATH, nó cũng cập nhật plugin. Nếu không, chạy hai lệnh sau rồi khởi động lại Claude Code:
claude plugin marketplace update plannotator
claude plugin update plannotator@plannotatorĐể gỡ cài, mặc định lệnh này giữ lại plan, lịch sử và cài đặt của bạn:
plannotator uninstallThêm --purge nếu muốn xoá cả dữ liệu cục bộ. Lệnh sẽ bắt bạn gõ chữ purge để xác nhận, và dữ liệu xoá rồi không lấy lại được. Dùng --dry-run để xem trước mà chưa xoá gì.
IV.Kiểm tra đã chạy được chưa
Cách nhanh nhất là thử các lệnh CLI. Liệt kê các phiên đang chạy:
plannotator sessionsHoặc mở Inbox. Nếu cài đúng, một cửa sổ trình duyệt cục bộ sẽ hiện ra:
plannotator inboxCách thứ hai là thử trong agent. Ví dụ với Claude Code, gõ lệnh sau với một file Markdown có sẵn. Nếu trình duyệt mở ra với nội dung file, bạn đã cài xong:
/plannotator-annotate README.mdNếu gõ plannotator mà terminal báo không tìm thấy lệnh, xem phần lỗi ở dưới.
V.Dùng vào việc thật
A.Duyệt plan trước khi agent bắt tay làm
Bạn là lập trình viên nhận task thêm tính năng. Bạn bật plan mode và giao việc cho agent. Khi agent viết xong plan, giao diện duyệt tự mở trên trình duyệt. Bạn thấy bước 3 sai hướng, bôi đen đoạn đó, ghi «dùng bảng có sẵn, đừng tạo bảng mới», rồi gửi. Agent nhận phản hồi, sửa plan, và bạn duyệt lại.
Kết quả: bạn chặn được hướng đi sai trước khi nó sinh ra hàng trăm dòng code cần xoá.
Đọc kỹ plan trước khi agent chạy sẽ rẻ hơn nhiều so với sửa code sau khi nó chạy xong.
Ông T
B.Ghi chú tài liệu như bản yêu cầu sản phẩm
Bạn là nhân viên văn phòng hay quản lý sản phẩm, có một bản mô tả yêu cầu viết bằng Markdown. Bạn muốn góp ý cho agent hoặc đồng đội. Mở bản đó bằng lệnh:
/plannotator-annotate report.mdBạn bình luận từng đoạn rồi gửi. README cũng có mẫu bản yêu cầu sản phẩm để bạn thử. Với file HTML, thêm cờ --render-html nếu muốn hiển thị nguyên trạng thay vì chuyển đổi:
/plannotator-annotate report.html --render-htmlKết quả: góp ý nằm đúng chỗ cần sửa, không phải copy từng đoạn sang khung chat.
C.Review pull request của đồng đội
Bạn là dev cần xem một PR trên GitHub. Chạy lệnh với đường link PR:
/plannotator-review <github-pr-url>Giao diện diff mở ra, bạn comment lên từng dòng, đề xuất sửa, và gửi phản hồi. Muốn xem thay đổi chưa commit của chính mình thì chạy /plannotator-review không kèm tham số. Với GitLab dùng đường link merge request. Nếu bạn xài Codex, thay lệnh slash bằng !plannotator review.
Kết quả: bạn có một chỗ duy nhất để đọc diff và để lại nhận xét.
D.Quản lý nhiều agent bằng Inbox
Bạn chạy vài agent cùng lúc ở nhiều dự án. Thay vì canh từng cửa sổ, bạn mở:
plannotator inboxCác agent để câu hỏi, file, bản duyệt vào đây. Bạn trả lời một cú bấm, và câu trả lời về đúng phiên đã hỏi. Với agent chưa có plugin riêng, README nói chúng nối qua MCP bằng plannotator inbox mcp.
Kết quả: bạn không phải nhảy qua lại giữa nhiều terminal để trả lời.
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 chưa nạp lại PATH sau khi cài. Đóng terminal, mở cái mới và thử lại. Nếu bạn cài bằng --minimal, file nằm ở ~/.local/bin, nên cần chắc thư mục này có trong PATH.
B.Lệnh /plannotator-... không hiện trong agent
Có thể bạn chưa khởi động lại agent, hoặc chưa làm bước riêng của agent đó (ví dụ cài plugin cho Claude Code). Làm đủ hai việc này rồi thử lại.
C.Plan review không bật ở Codex trên Windows
README ghi hook của Codex trên Windows gốc còn ở mức thử nghiệm, và trình cài chỉ in các bước cài tay. Bạn làm theo các bước đó, hoặc dùng WSL, vì README nói bản macOS, Linux, WSL bật tự động.
D.Báo cáo lỗi khi duyệt PR GitHub hoặc GitLab
README nói tính năng này dùng CLI đã đăng nhập của bạn. Vì vậy hãy kiểm tra CLI của GitHub hoặc GitLab đã đăng nhập chưa. README chưa liệt kê chi tiết lệnh kiểm tra, nên bạn xem mục tài liệu cài đặt trên trang dự án.
E.Muốn gỡ mà bị từ chối
Lệnh gỡ cố ý giữ lại file chạy nếu không đọc được file cấu hình của một agent, hoặc còn hook do bên khác cài vẫn gọi Plannotator. Thông báo lỗi sẽ nêu tên file và cách xử lý. Làm theo hướng dẫn đó rồi chạy lại plannotator uninstall.
VII.Có nên dùng không
Điểm mạnh. Một công cụ phủ nhiều agent, cài bằng một dòng, và gom việc duyệt plan, tài liệu, diff về một giao diện quen thuộc là trình duyệt. README nói Plannotator không thu thập dữ liệu sử dụng hay phân tích, và plan, 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.
Giới hạn cần biết.
- Mỗi lần mở, các giao diện duyệt có kiểm tra bản phát hành mới trên GitHub. README nói việc này không gửi nội dung của bạn, nhưng hiện chưa có tuỳ chọn tắt.
- Duyệt Git cục bộ có thể hỏi
originbằnggit ls-remoteđể dò nhánh mặc định. Bạn tắt được bằngplannotator review --no-git-remote-check, hoặcPLANNOTATOR_GIT_REMOTE_CHECK=0. - Một số tính năng cần mạng: chú thích đường link web (qua Jina Reader theo mặc định), Ask AI và các agent review (gửi ngữ cảnh tới nhà cung cấp bạn chọn), và chia sẻ.
- Link chia sẻ bản nhỏ nằm trong phần fragment của URL và không được mã hoá. Ai có đủ link đều đọc được. Bản lớn dùng dịch vụ link ngắn có mã hoá AES-256-GCM và hết hạn sau 7 ngày. Bạn có thể tắt chia sẻ hoàn toàn bằng
PLANNOTATOR_SHARE=disabled. - Workspaces là sản phẩm lưu trữ riêng, nên mô hình «dữ liệu ở máy bạn» không áp dụng cho nội dung đặt ở đó.
- Một số agent chưa hỗ trợ đầy đủ. Ví dụ Droid hiện chỉ có lệnh, chưa chặn được plan.
Khi nào nên chọn cách khác. Nếu bạn chỉ làm việc với một agent và vài đoạn plan ngắn, việc chat thẳng với agent có thể đã đủ. Nếu bạn không muốn cài thêm gì vào cấu hình agent, hãy dùng --minimal hoặc cân nhắc không dùng. Nếu cần cộng tác nhóm lâu dài, hãy đọc kỹ chính sách về Workspaces trên trang dự án trước khi đưa nội dung nhạy cảm vào.
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à bản mã nguồn mở chạy cục bộ. README không nêu giá cho phần cài đặt cơ bản. Workspaces là sản phẩm lưu trữ riêng, và tư liệu mình có chưa nói về giá của nó.
Có chạy được trên Windows không?
Có lệnh cài riêng cho Windows PowerShell (irm https://plannotator.ai/install.ps1 | iex). Tuy vậy với Codex trên Windows gốc, hook còn ở mức thử nghiệm và trình cài chỉ in ra các bước cài tay. WSL cũng được README liệt kê là môi trường hỗ trợ.
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 trợ lý cá nhân như Grok Bot, Muse, Hermes và OpenClaw. Mức hỗ trợ khác nhau tuỳ agent, ví dụ Droid chỉ có lệnh.
Dữ liệu của mình có an toàn không?
README nói không có telemetry hay phân tích sử dụng, và plan, diff, ghi chú, lịch sử, cấu hình mặc định nằm trên máy bạn. Dữ liệu chỉ rời máy khi bạn dùng tính năng cần mạng như đọc URL, Ask AI, review bằng AI hay chia sẻ link. Giao diện cũng kiểm tra bản mới trên GitHub mỗi lần mở, và hiện chưa có cách tắt.
Có cần GPU hay API key riêng không?
README không yêu cầu GPU. Về API key, tư liệu chưa nói rõ. Các tính năng AI gửi nội dung tới nhà cung cấp bạn đã cấu hình, nên cần xem tài liệu của dự án để biết chi tiết.
Làm sao gỡ cài đặt?
Chạy plannotator uninstall. Mặc định lệnh này giữ lại plan, lịch sử và cài đặt của bạn. Thêm --purge để xoá cả dữ liệu cục bộ, và dùng --dry-run để xem trước. Dữ liệu đã xoá bằng purge không khôi phục được.
Khác gì so với chat trực tiếp với agent?
Plannotator cho bạn bôi đen và bình luận đúng chỗ trên plan, tài liệu hoặc diff, rồi gửi toàn bộ phản hồi về agent chỉ với một cú bấm. Tư liệu mình có không so sánh với công cụ cụ thể nào khác.


