Pattern kiểm agent

UI Review Gate

Review plan và diff của agent trong browser bằng Plannotator

Plannotator không thay coding agent. Nó thêm một checkpoint trong browser trước khi agent đi tiếp, để bạn kiểm tra plan, diff, hoặc message trực quan rồi trả feedback cụ thể.

Plan Diff Message

Một pattern, không chỉ là tool

UI Review Gate là pattern checkpoint; Plannotator là tool hiện thực nó.

Review ngay trong browser

Plan, diff, file, folder, URL và message mới nhất của agent đều mở trong một UI review trực quan.

Feedback quay lại agent

Approve để đi tiếp, hoặc gửi annotation để agent sửa plan/code trước.

Vì sao cần visual gate

Plan dài rất khó review trong terminal

Terminal là một surface kém để review plan dài: không có chỗ đánh dấu vị trí cụ thể, và đọc một khối chữ dày làm não mệt. Visual UI giải quyết cả hai — bạn đọc như một tài liệu và annotate đúng ngay chỗ cần sửa.

Trong terminal

Plan dài trôi mất

Plan nhiều bước hoặc diff lớn trôi qua trong terminal. Bạn phải giữ cả plan trong đầu để theo dõi.
Đọc một bức tường chữ rất mệt

Đọc một khối chữ dày, không cấu trúc làm não mệt nhanh, nên lỗi thật dễ lọt qua.
Feedback gõ lại từ trí nhớ

Không có chỗ đánh dấu dòng cụ thể, nên bạn mô tả lại từ trí nhớ và mong agent hiểu đúng chỗ.

Trong Plannotator

Annotate đúng nơi cần sửa

Comment inline, ngay dòng hoặc block cần sửa. Ghi chú gắn chặt vào đúng vị trí đó.
Plan dài trở nên dễ quét

Plan hoặc diff mở ra như một tài liệu có cấu trúc, điều hướng được, nên review dài nhẹ đầu hơn hẳn.
Feedback chính xác, gửi thẳng agent

Mỗi annotation mang theo vị trí và ngữ cảnh, nên agent nhận feedback chính xác thay vì mô tả mơ hồ.

Gate này cover gì

Một pattern, nhiều mặt review

Cùng một vòng lặp dùng được cho plan, code diff, trang HTML render, folder docs, hoặc response agent vừa gửi.

Agent bị tạm dừng suốt thời gian review đang mở. Không gì chạy tiếp cho tới khi bạn approve, nên gate này chặn theo thiết kế — không phải notification dễ bỏ lỡ.

Gate review plan

Claude Code dùng hook PermissionRequest cho ExitPlanMode. Codex dùng Stop hook đọc plan mới nhất từ rollout transcript.

Review code và diff

Lệnh review mở UI review diff cho thay đổi hiện tại hoặc PR/MR URL, rồi trả feedback về agent session.

Annotate artifact

Lệnh annotate xử lý Markdown, HTML, URL, folder; lệnh last mở message mới nhất của assistant.

Port hợp remote

Remote mode và fixed port giúp server chạy qua forwarded port, devcontainer, hoặc tunnel.

Revision và session

Plan submit lại có thể hiện diff. Session có thể liệt kê, mở lại theo số, hoặc dọn khi cũ.

Share link khi phù hợp

Review nhỏ có thể share bằng dữ liệu trong URL hash. Short link cho nội dung lớn là opt-in và encrypted; việc share có thể tắt khi nội dung nhạy cảm.

Hook lifecycle

Plannotator chen vào lifecycle ở đâu

Gate này không chỉ là UI command. Mỗi host gắn nó vào một điểm lifecycle riêng, rồi Plannotator đổi approve/feedback thành response đúng kiểu hook của host đó.

Cài mặc định ưu tiên review plan. Hook review file và response là recipe opt-in.

Claude Code

Trước khi Claude thoát plan mode

PermissionRequest -> ExitPlanMode

Vai trò: Chặn bước bàn giao plan, đọc tool_input.plan từ stdin, mở review gate trên browser, rồi chỉ cho Claude đi tiếp sau khi approve.
Bật: Cài Plannotator plugin từ Claude marketplace, hoặc thêm hook PermissionRequest match ExitPlanMode trong ~/.claude/settings.json.
Tắt: Tắt/gỡ plugin, hoặc xoá entry PermissionRequest đó. Restart Claude Code sau khi đổi hook.

Codex

Sau khi turn Codex dừng với plan

Stop

Vai trò: Đọc transcript_path, lấy plan mới nhất hoặc <proposed_plan>, mở review, rồi trả feedback để Codex revise khi có annotation.
Bật: Installer tự bật trên macOS/Linux/WSL khi có ~/.codex. Setup tay dùng [features] hooks = true và Stop hook trong hooks.json.
Tắt: Xoá entry Stop hook, hoặc tắt hooks ở config layer Codex đó nếu muốn disable toàn bộ hooks tại layer ấy.

OpenCode

Khi plan agent submit plan

plan-agent submit_plan

Vai trò: Plugin npm expose submit_plan cho plan agent mặc định, nên có thể gate bước planning mà không đưa tool này cho build agents.
Bật: Thêm @plannotator/opencode vào opencode.json rồi restart OpenCode. Chạy installer nếu muốn có thêm /plannotator-* commands.
Tắt: Gỡ plugin hoặc chuyển workflow sang manual để chỉ dùng commands. Chỉ dùng all-agents khi thật sự muốn mở tool rộng.

Recipe hook opt-in

`PostToolUse -> Write`

Review mỗi file agent vừa ghi. Hợp với docs nhạy cảm, HTML generate, hoặc file cần soi copy/visual kỹ.

`Stop -> annotate-last`

Review câu trả lời cuối turn. Approve thì kết thúc sạch; annotation sẽ gửi feedback lại vào vòng agent.

`--hook` / `--gate` / `--json`

--hook biến command thành gate và xuất JSON đúng format hook. --gate thêm nút approve. --json dùng cho wrapper/log.

Công tắc runtime

Dùng PLANNOTATOR_REMOTE=1 khi browser ở máy khác, VM, devcontainer, hoặc URL Tailscale.
Set PLANNOTATOR_PORT khi test mobile cần QR/link ổn định.
Set PLANNOTATOR_BROWSER hoặc BROWSER khi hook cần mở browser cụ thể.
Set PLANNOTATOR_SHARE=disabled khi gate phải local-only.
Chạy lại installer hoặc xoá config hook khi chuyển giữa automatic gate và workflow chỉ dùng command.

Cài đặt và setup

Setup trong ba bước

Một installer lo cho mọi agent. Chạy nó, làm nốt một bước mà agent của bạn cần, rồi thử một command. Không cần cấu hình phức tạp.

1
Chạy installer

Nó thêm binary plannotator, tự nhận diện agent đã cài, và tự nối hook, skill, slash command cho từng cái.
install
```
# macOS / Linux / WSL
$curl -fsSL https://plannotator.ai/install.sh | bash

# Windows PowerShell
$irm https://plannotator.ai/install.ps1 | iex
```
2
Set up agent của bạn

Tìm agent của bạn bên dưới và làm bước của nó. Agent gắn nhãn tự động thì không cần làm gì sau installer.

Claude Code

Thêm marketplace plugin, rồi install plannotator@plannotator, và restart.

Codex tự động

Không cần gì. Tự động qua Stop hook experimental (macOS/Linux/WSL; tắt trên Windows). Có sẵn skill $plannotator-*.

Gemini CLI tự động

Không cần gì — hook, policy, slash command tự cấu hình. Cần Gemini CLI 0.36.0+.

OpenCode

Thêm @plannotator/opencode@latest vào danh sách plugin trong opencode.json, rồi restart.

Copilot CLI

Thêm marketplace, install plannotator-copilot@plannotator. Plan review chạy trong plan mode (Shift+Tab).

Amp

Copy plannotator.ts vào ~/.config/amp/plugins/ và reload. Workflow nằm trong command palette.

Droid

Thêm marketplace, rồi install plannotator@plannotator. Chỉ có commands, chưa chặn plan.

Kiro CLI tự động

Không cần gì — skill và agent ví dụ tự cài. Thử kiro-cli chat --agent plannotator.

Pi

Bỏ qua installer: pi install npm:@plannotator/pi-extension. Khởi động --plan hoặc bật /plannotator.
Claude Code: hook thủ công (không dùng plugin system)
~/.claude/settings.json
```
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          { "type": "command", "command": "plannotator", "timeout": 345600 }
        ]
      }
    ]
  }
}
```

Thử ngay

Tự gọi command khi cần. Auto plan review chỉ chạy khi host agent đi tới lifecycle hook đã nối Plannotator; plan file do CK tạo nên mở thủ công bằng annotate.

try it

/plannotator-last                   # annotate the agent's last reply
/plannotator-review                 # review your current diff, PR-style
/plannotator-annotate plans/<plan>/plan.md # review a CK plan file
/plannotator-annotate report.html   # annotate any file, folder, or URL

Approve bằng mobile

Remote control và Plannotator UI là hai kênh riêng

Codex hoặc Claude Code mobile có thể approve hành động agent qua kênh remote-control riêng. Approval của Plannotator diễn ra trong browser trỏ tới server Plannotator, nên phone phải truy cập được server đó.

Cùng Wi-Fi

Mở host LAN URL trên phone. 127.0.0.1 không chạy vì nó trỏ về chính phone.

Khác network

Dùng Tailscale, VPN, hoặc tunnel. Link chỉ chạy khi session Plannotator đó còn sống.

mobile remote access

$export PLANNOTATOR_REMOTE=1
$export PLANNOTATOR_PORT=9999

# Same Wi-Fi
$open http://<host-lan-ip>:9999

# Tailscale Serve example
$tailscale serve --bg --tcp=10000 9999
$open http://<tailscale-ip>:10000/

Checklist debug

Port chưa listen: mở session Plannotator mới và kiểm tra URL/port in ra terminal.
Phone không connect: kiểm tra cùng Wi-Fi, firewall, hoặc Tailscale/VPN đã connect ở cả hai máy.
MagicDNS lỗi: dùng Tailscale IP trước, xử DNS sau.
HTTP vs HTTPS: URL local của Plannotator thường là HTTP trừ khi tunnel thêm TLS.
Session cũ: chạy plannotator sessions --clean, rồi mở review mới.

Fit với ClaudeKit

Có — chạy song song với ClaudeKit

Hai bên làm hai việc khác nhau nên ghép rất hợp. ClaudeKit lo phần chạy — plan, cook, review, test. Plannotator là cổng review của con người: surface trong browser để bạn kiểm thứ CK tạo ra và gửi feedback chính xác. Chỉ auto-block khi lifecycle hook của host được kích hoạt.

Quy tắc ngắn: Claude Code ExitPlanMode, Codex Stop, OpenCode submit_plan, và Pi plan mode có thể tự mở Plannotator. Một lần chạy /ck:plan bình thường của ClaudeKit là command tạo plan, nên xem Plannotator là bước review gọi rõ ràng.

Cách dùng chung

1
Plan bằng ClaudeKit, rồi gate artifact
/ck:plan → /plannotator-annotate plans/.../plan.md

/ck:plan tạo artifact plan của CK; nó không tự đồng nghĩa với plan mode của host. Khi cần browser review gate, mở file plan.md đã tạo bằng Plannotator.
2
Implement, rồi review diff
/ck:cook → /plannotator-review

Để /ck:cook xử lý plan đã duyệt. Trước khi commit, mở diff bằng /plannotator-review và comment inline ngay các dòng cần sửa.
3
Review docs và artifact
/plannotator-annotate ./docs

Annotate Markdown, HTML, hoặc folder như ./docs trên cùng một review surface, không cần setup thêm.

Giữ chúng là hai tool riêng. Dùng Plannotator song song với ClaudeKit, không merge vào trong — như vậy CK không phải gánh UI server và browser state, và mỗi bên cập nhật theo nhịp riêng.

Khi không nên dùng

Chỉ dùng gate khi đáng dừng lại để review

Không cần browser gate cho sửa rất nhỏ, dễ revert, diff đọc inline nhanh hơn.
Không share plan nhạy cảm nếu chưa tắt sharing hoặc team chưa chấp nhận privacy model của URL/short-link.
Đừng xem approval là kết quả test. Vẫn phải chạy test, build, và đối chiếu source sau khi agent sửa code.

Nguồn tham khảo

Tài liệu chính thức

Installation guide Plan review lifecycle Hook integration recipes Remote and devcontainers GitHub repository