Mổ xẻ Plannotator: Tầng review trực quan kẹp giữa bạn và AI Coding Agent

Nếu đã từng dùng Claude Code, OpenCode hay bất kỳ AI coding agent nào chạy trong terminal, chắc chắn bạn đã từng gặp tình huống này:

Bạn giao cho agent một việc phức tạp: “Tái cấu trúc lại module auth, chuyển từ JWT thuần sang Passkey WebAuthn nhưng vẫn phải giữ tương thích ngược”.

Con agent bắt đầu suy nghĩ, bật Plan Mode, rồi tuôn ra một bản kế hoạch markdown dài hơn trăm dòng trong terminal. Nó liệt kê chi tiết từng file chuẩn bị sửa, từng schema cơ sở dữ liệu sẽ đổi, rồi dừng lại ở dấu nhắc:

Do you want to proceed with this plan? (y/n)

Lúc này bạn rơi vào thế kẹt. Bấm y để nó tự chạy thì không yên tâm: nhỡ bước 3 nó hiểu sai logic session của Redis, hoặc bước 6 nó xóa mất file helper dùng chung thì dự án gãy vụn. Nhưng nếu muốn sửa thì sao? Bạn phải ngồi gõ từng đoạn văn bản trong cái cửa sổ terminal chật hẹp: “Ở bước 3 đừng dùng thư viện ngoài, sửa lại hàm verify trong file utils.ts theo helper có sẵn…”. Gõ xong đoạn chỉ dẫn đó thì bạn tự vào sửa code còn nhanh hơn.

backnotprop/plannotator ra đời để giải quyết đúng điểm nghẽn trải nghiệm đó. Không phải bằng cách làm cho model thông minh hơn, mà bằng cách thay đổi hoàn toàn cách con người kiểm soát agent khi duyệt kế hoạch.

Tóm tắt (TL;DR)

Đúc kết nhanh:

• Plannotator là gì? Công cụ mã nguồn mở chạy local, tự động kẹp một giao diện web trực quan vào giữa bạn và AI coding agent mỗi khi agent chuẩn bị thực thi kế hoạch hoặc sinh mã nguồn.
• Chấm dứt cảnh gõ chữ sửa plan: Thay vì gõ mô tả trong terminal, Plannotator mở tab trình duyệt để bạn dùng chuột bôi đen đoạn sai, gạch bỏ bước thừa, thả comment trực tiếp vào vị trí cần sửa.
• Cơ chế non-blocking (Claude Code 2.1.287+): Giải phóng terminal. Con agent kết thúc turn sạch sẽ thay vì đóng băng shell để ngồi đợi bạn, giúp bạn thong thả đọc plan mà không sợ đứt phiên làm việc.
• Đa nền tảng & Đa VCS: Hỗ trợ Claude Code, OpenCode, Codex và kết nối qua MCP; tích hợp sâu cả Git, GitButler, Jujutsu (jj) và Perforce (p4).
• Mã nguồn: backnotprop/plannotator trên GitHub (Apache 2.0 / MIT).

---

Mô hình hoạt động: Trả terminal về đúng việc của nó

Cốt lõi vấn đề nằm ở chỗ: Terminal sinh ra để chạy lệnh và stream log, không phải để con người đọc hiểu và phản biện một bản thiết kế kiến trúc đa bước.

Khi con agent đưa ra một kế hoạch 10 bước trải rộng trên 6 file, bạn cần thao tác trực quan: gạch bỏ bước vô lý, đánh dấu bước cần lưu ý, và viết vài chữ ghi chú ngay bên cạnh. Bạn không thể làm việc đó hiệu quả bằng các phím mũi tên và dòng lệnh trắng đen.

Plannotator kẹp vào đúng điểm giao nhau này:

---

Trải nghiệm thực tế: Khi duyệt plan biến thành việc bôi đen và gạch chéo

Cơ chế hoạt động của Plannotator rất trực diện. Nó không can thiệp vào model weights, mà gắn một hook vào vòng lặp sự kiện của agent.

1. Bắt quả tang khoảnh khắc ExitPlanMode

Trong Claude Code, khi agent hoàn thành việc suy nghĩ và chuẩn bị bắt tay vào sửa file, nó sẽ gọi tool nội bộ ExitPlanMode.

Plannotator đăng ký một hook hệ thống lắng nghe đúng sự kiện này:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}

Ngay khi Claude Code phát tín hiệu muốn rời Plan Mode, hook của Plannotator lập tức can thiệp:

1. Đọc toàn bộ nội dung markdown của kế hoạch từ luồng dữ liệu chuẩn (stdin).
2. Dựng chớp nhoáng một web server siêu nhẹ ngay trên máy bạn (mặc định chọn port ngẫu nhiên).
3. Tự động mở tab trình duyệt (hoặc tab webview trong VS Code nếu bạn dùng extension).

Trước mắt bạn lúc này không còn là dòng chữ y/n cộc lốc nữa, mà là một trang tài liệu đầy đủ tính năng:

• Muốn bỏ bước 5? Bạn rê chuột gạch chéo (strike-through).
• Bước 7 dùng sai schema? Bạn bôi đen đoạn đó, gõ ghi chú ngắn: “Dùng column user_id thay vì account_id”.
• Xong xuôi? Bấm nút Send Feedback. Toàn bộ ghi chú được tuần tự hóa thành ngữ cảnh có cấu trúc gửi ngược lại cho agent. Agent đọc xong sẽ tự động viết lại kế hoạch mà bạn không tốn thời gian gõ giải thích thủ công.

2. Cơ chế Non-Blocking trên Claude Code 2.1.287+

Trước đây, khi một tool đánh chặn terminal, nó sẽ giữ chặt tiến trình. Terminal của bạn bị treo cứng. Nếu kế hoạch phức tạp và bạn cần 15 phút đọc kỹ, terminal vẫn phải nằm chờ ở đó. Nếu mạng chập chờn hoặc bạn đóng terminal, phiên làm việc sẽ bị đứt.

Từ Claude Code 2.1.287+, Plannotator kích hoạt sẵn cơ chế ngắt luồng bất đồng bộ (có thể tắt bằng PLANNOTATOR_CLAUDE_MOD=0 nếu muốn quay về cách cũ):

• Ngắt luồng sạch sẽ: Thay vì ép Claude Code treo máy chờ phản hồi, hook ra hiệu cho Claude kết thúc turn hội thoại hiện tại ngay lập tức.
• Terminal hoàn toàn tự do: Bạn có thể tiếp tục gõ lệnh khác trong terminal, kiểm tra file, hoặc đóng máy đi làm việc khác.
• Phản hồi như một turn mới: Khi bạn đọc xong trên trình duyệt và bấm “Approve”, Plannotator gửi quyết định đó về dưới dạng một lượt nhập liệu tiếp theo. Con agent thức dậy, nhận toàn bộ ghi chú của bạn và bắt đầu chạy tiếp.

3. Plannotator Inbox: Trung tâm gom việc cho hệ thống đa agent

Một tính năng lớn gần đây của Plannotator là Plannotator Inbox.

Khi chạy song song nhiều agent (ví dụ một terminal chạy Claude Code sửa backend, một cửa sổ OpenCode viết unit test), bạn có thể chạy lệnh plannotator inbox mcp để biến Plannotator thành một MCP server. Bất kỳ con agent nào cần con người duyệt plan hoặc review diff đều có thể đẩy yêu cầu vào một hàng đợi duy nhất trên web. Bạn chỉ cần mở một tab duy nhất là có thể lần lượt duyệt qua từng quyết định của nhiều agent mà không cần chuyển đổi liên tục giữa các cửa sổ terminal.

---

Những góc khuất và bài học thực chiến

Khi đưa Plannotator vào quy trình làm việc thực tế, có hai cạm bẫy kỹ thuật và một rủi ro bảo mật quan trọng cần lưu ý:

1. CẢNH BÁO BẢO MẬT: Chạy Remote Mode qua SSH hoặc Docker

Khi làm việc trên server từ xa hoặc trong container không có giao diện đồ họa, lệnh gọi trình duyệt mặc định (xdg-open hoặc open) sẽ thất bại. Để khắc phục, bạn có thể chuyển sang remote mode:

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=19432
export PLANNOTATOR_BROWSER=none

LƯU Ý BẢO MẬT BẮT BUỘC:
Khi bật PLANNOTATOR_REMOTE=1, server Plannotator sẽ lắng nghe trên địa chỉ 0.0.0.0 và hoàn toàn không có cơ chế xác thực đăng nhập (no auth). Bất kỳ ai truy cập được vào cổng 19432 đều có thể xem toàn bộ kế hoạch, đọc code và gửi phản hồi giả mạo vào agent.
Giải pháp an toàn: Không bao giờ mở cổng 19432 ra internet công cộng trên firewall/security group. Luôn sử dụng SSH tunnel cục bộ:

ssh -L 19432:localhost:19432 user@remote-server

Hoặc giới hạn truy cập qua mạng nội bộ Tailscale.

2. Nguy cơ lạm phát token do ghi chú quá đà

Khi có một giao diện trực quan cho phép bôi đen và comment, lập trình viên rất dễ mắc thói quen bắt bẻ vụn vặt: sửa từng câu chữ, bắt đổi tên từng biến phụ.

Hãy nhớ rằng: Mỗi dòng comment bạn viết trên web đều được chuyển thành prompt chỉ dẫn gửi vào context window của agent. Nếu bạn để lại hàng chục ghi chú chi li, bạn đang tiêu tốn thêm lượng lớn token ngữ cảnh và làm phân tán sự chú ý của mô hình khỏi logic kiến trúc cốt lõi. Hãy tập trung ghi chú vào những điểm trọng yếu: cấu trúc dữ liệu, các bước migration nhạy cảm và quy tắc nghiệp vụ.

---

Bắt đầu trong 2 phút

Cài đặt file nhị phân độc lập (script cài đặt đã tự động nhận diện và cấu hình hook cho Claude Code):

# Cài đặt file thực thi nhị phân độc lập
curl -fsSL https://plannotator.ai/install.sh | bash

Nếu muốn cài thủ công qua hệ thống plugin của Claude Code:

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

Sau khi cài đặt xong, bạn làm việc với Claude Code bình thường. Lần tới khi agent kích hoạt Plan Mode, tab review trực quan sẽ tự động bật lên.

---

Lời kết (Final Take)

Sự phát triển của những công cụ như Plannotator phản ánh một quy luật rõ ràng: Khi năng lực sinh mã của mô hình AI đã vượt qua ngưỡng cơ bản, điểm nghẽn hiệu suất không còn nằm ở việc AI viết nhanh hay chậm, mà nằm ở việc con người kiểm soát và định hướng nó tốn bao nhiêu công sức.

Hãy để terminal tập trung vào việc chạy lệnh và theo dõi tiến trình, còn việc đọc hiểu và định hướng kế hoạch nên được giao cho một giao diện trực quan có băng thông tương tác cao hơn.

---

Câu hỏi thường gặp (FAQ)

1. Dữ liệu kế hoạch có bị chia sẻ ra ngoài không?

Theo mặc định, Plannotator có tính năng chia sẻ qua room.plannotator.ai. Nếu bạn làm việc trên dự án nội bộ và muốn đảm bảo bảo mật tuyệt đối, hãy tắt hoàn toàn tính năng này bằng cách khai báo:

export PLANNOTATOR_SHARE=disabled

Ngoài ra, mỗi lần khởi động công cụ sẽ kiểm tra phiên bản mới từ GitHub, tính năng URL annotation có thể truy vấn qua Jina, và tính năng “Ask AI” sẽ gửi ngữ cảnh tới nhà cung cấp mô hình bạn cấu hình.

2. Plannotator có hỗ trợ xem code diff thực tế không?

Có. Ngoài việc bắt ExitPlanMode để duyệt kế hoạch, Plannotator tích hợp sẵn trình review diff hai cột, hỗ trợ Git, GitButler, Jujutsu (jj) và Perforce (p4).

3. Làm thế nào để mở lại phiên review cũ nếu lỡ đóng tab?

Để duyệt lại danh sách các phiên review đã lưu, bạn chạy lệnh:

plannotator sessions
# Hoặc mở trực tiếp phiên số N:
plannotator sessions --open <N>

Trong khi đó, lệnh /plannotator-last bên trong Claude Code dùng để gửi yêu cầu xem lại tin nhắn phản hồi gần nhất của agent.