# Plannotator: duyệt kế hoạch và code của AI agent — hướng dẫn cài đặt và dùng

> 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.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-12 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/plannotator-duyet-ke-hoach-code-ai-agent

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.

```repo
- repo | backnotprop/plannotator
- kind | Repo
- desc | 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.
- stars | 10k
- lang | TypeScript
- license | Apache-2.0
```

## Plannotator làm được gì

### 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.

### 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.

### 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.

### 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.

### 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.

### 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.

## 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 `Stop` thử 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.

## Cài đặt từng bước

```steps
- Chạy bộ cài | Mộ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 agent | Tuỳ 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ệnh | Mở thử annotate hoặc review để xem trình duyệt bật lên
```

### 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:

```bash
curl -fsSL https://plannotator.ai/install.sh | bash
```

Windows PowerShell:

```powershell
irm https://plannotator.ai/install.ps1 | iex
```

Bạ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`:

```bash
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal
```

### 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:

```bash
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
```

Sau đó khởi động lại Claude Code.

**Copilot CLI:**

```bash
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@plannotator
```

Khở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:

```json
"plugin": ["@plannotator/opencode@latest"]
```

**Pi** — bỏ qua bộ cài, chạy:

```bash
pi install npm:@plannotator/pi-extension
```

Rồi chạy Pi với `--plan`, hoặc bật tắt bằng `/plannotator-plan-mode`.

**Droid:**

```bash
droid plugin marketplace add https://github.com/backnotprop/plannotator
droid plugin install plannotator@plannotator
```

Vớ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.

### 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:

```bash
claude plugin marketplace update plannotator
claude plugin update plannotator@plannotator
```

Rồi khởi động lại Claude Code. Với Pi: `pi update --extensions`.

### 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:

```bash
plannotator uninstall
```

Muố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ì.

```bash
plannotator uninstall --purge
```

## 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:

```bash
/plannotator-annotate README.md
```

Nế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:

```bash
plannotator sessions
```

Lệ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.

## Dùng vào việc thật

### 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

### 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:

```bash
/plannotator-annotate README.md
/plannotator-annotate https://docs.rs/…
/plannotator-annotate report.html --render-html
```

Dò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`.

### 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õ:

```bash
/plannotator-review
```

Lệ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:

```bash
/plannotator-review <github-pr-url>
```

Bình luận của bạn quay về agent để nó sửa tiếp.

### 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:

```bash
plannotator inbox
```

Agent để 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.

```note
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.
```

## Lỗi hay gặp và cách xử lý

### 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.

### 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`.

### 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.

### 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.

### 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`.

## 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.
