VividKit Crystal clear AI coding
EN
Giới Thiệu ClaudeKit Hướng Dẫn ClaudeKit CLI Tìm Lệnh Phù Hợp Bảng Lệnh Nhanh Quy Trình Mẫu Tham Chiếu CLI Claude Mechanics Permission Modes ClaudeKit Hooks Coexistence Cách ClaudeKit Hoạt Động UI Review Gate Tìm Unknowns Của Bạn Inside ClaudeKit Chuyển Đổi Tài Khoản Cấu Hình IDE Remote Control Codex App ClaudeKit x Codex Migrate sang Tool Khác Khôi Phục Session Sửa Lỗi Từ Log Thiết Kế UI/UX Khuyến Mãi Ủng Hộ VividKit

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

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

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

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

    macOS / Linux / WSL

    Chạy lệnh này trong terminal.

    macOS / Linux / WSL 
    curl -fsSL https://plannotator.ai/install.sh | bash

    Windows PowerShell

    Chạy lệnh này trong PowerShell.

    Windows PowerShell 
    irm https://plannotator.ai/install.ps1 | iex
  2. 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)

    Chỉ dùng fallback này khi không cài được plugin Claude Code. Merge block này vào ~/.claude/settings.json, giữ nguyên settings đang có, rồi restart Claude Code. Để test, vào built-in plan mode rồi thoát plan mode; Plannotator sẽ tự mở.

    ~/.claude/settings.json 
    {
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          { "type": "command", "command": "plannotator", "timeout": 345600 }
        ]
      }
    ]
  }
}
  3. 3

    Thử ngay

    Tự gọi một command khi cần. Auto plan review không áp dụng cho mọi plan; nó chỉ chạy trong flow đã bật Plannotator hook. Ví dụ: trong built-in plan mode, khi bạn thoát plan mode thì review sẽ tự mở. Plan file do CK tạo nên mở thủ công để review.

    Reply mới nhất của assistant

    Mở message mới nhất của assistant để comment.

    try it 
    /plannotator-last

    Diff hiện tại

    Review working tree như một PR nhỏ.

    try it 
    /plannotator-review

    Plan file của CK

    Mở thủ công plan file do ClaudeKit lưu ra disk.

    try it 
    /plannotator-annotate plans/<plan>/plan.md

    Artifact bất kỳ

    Annotate Markdown, HTML, folder, hoặc URL.

    try it 
    /plannotator-annotate report.html

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

1

Mở review trên desktop

Plannotator chạy cạnh agent và mở một browser UI.

2

Mở URL phone truy cập được

Dùng LAN IP nếu cùng Wi-Fi, hoặc tunnel nếu khác network.

3

Approve hoặc comment từ mobile

Quyết định sẽ gửi ngược về session agent trên desktop.

Setup host

Mở Plannotator server từ máy host chạy agent

Set PLANNOTATOR_REMOTE và PLANNOTATOR_PORT ở nơi host agent đọc ENV.

Claude Code

~/.claude/settings.json

Dùng user settings cho mọi project, hoặc .claude/settings.local.json nếu chỉ muốn áp dụng cho một repo.

json · Claude Code env 
{
  "env": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  }
}

Codex

~/.codex/config.toml

Dùng user config cho mọi project, hoặc .codex/config.toml trong repo đã trusted. Nếu table đã có sẵn thì merge vào table hiện có.

toml · Codex command env 
[shell_environment_policy]
inherit = "core"
set = { PLANNOTATOR_REMOTE = "1", PLANNOTATOR_PORT = "9999" }

Sau khi sửa provider config, restart session host agent để các command Plannotator mới nhận được biến ENV.

Verify đã chạy

Phone phải thấy UI review của Plannotator. Approve hoặc comment ở đó; quyết định sẽ gửi ngược về session agent trên desktop.

Route trên phone

Mở URL phone truy cập được trong browser

Chọn route ngắn nhất trước. Cùng Wi-Fi là đơn giản nhất; Tailscale, VPN, hoặc tunnel dùng khi khác network.

Cùng Wi-Fi

Mở host LAN URL. 127.0.0.1 trỏ về chính phone.

Khác network

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

Cùng Wi-Fi

Dùng LAN address của máy host

Tìm LAN IP của máy host trước, rồi mở URL Plannotator trong browser trên phone.

1

Tìm IP host

Chạy một command đúng với OS của máy host.

macOS 
ipconfig getifaddr en0
Linux / WSL 
hostname -I | awk '{print $1}'
Windows PowerShell 
ipconfig | findstr IPv4
2

Mở trên phone

Thay placeholder bằng IP lấy ở bước 1.

phone browser URL 
http://<host-lan-ip>:9999

Khác network

Mở port qua private route

Dùng cách này khi phone không cùng Wi-Fi với máy host chạy agent.

1

Mở local port

Dùng private route từ máy host.

Tailscale 
tailscale ip -4
tailscale serve --bg --tcp=10000 9999
2

Mở trên phone

Dùng route IP khi tunnel còn active.

phone browser URL 
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. 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. 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. 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.

Review artifact plan của CK

Sau khi `/ck:plan` ghi plan file, mở đúng file `plan.md` đó bằng Plannotator. Khi bạn send feedback trong browser, annotations sẽ quay lại session agent hiện tại và agent nên revise plan trước khi implement. Chỉ cần hỏi lại nếu review diễn ra ngoài session này.

claude code · plan gate 
# 1) Ask ClaudeKit to produce the plan artifact
/ck:plan "Build the feature and save a phased implementation plan"

# 2) Use the real path printed by /ck:plan
/plannotator-annotate plans/<plan-slug>/plan.md

# 3) In the browser, comment on:
# - requirements, scope, assumptions, risks
# - phase order and acceptance criteria per phase
# - missing tests, rollback, docs impact
# - unresolved questions before implementation

# 4) Send feedback / finish the browser review
# The annotations return to this agent session.
# The agent should revise the plan from those notes before implementation.

Dùng cùng gate cho các flow sau

Cùng pattern này dùng được sau cook, test, code review, hoặc docs generation. Mở diff hoặc artifact cần người đánh giá, annotate nó, rồi gửi feedback lại cho agent.

claude code · downstream gates 
# After the approved plan, let ClaudeKit implement
/ck:cook

# Review the actual working-tree diff before commit
/plannotator-review

# Review other artifacts CK or the agent produced
/plannotator-annotate reports/<run>/test-report.md
/plannotator-annotate reports/<run>/review.md
/plannotator-annotate ./docs

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