# Claude Code Monitor Bản build nội bộ SmartGift. Dashboard local-first cho Claude Code: hooks POST mỗi tool call lên server Express + SQLite, React UI cập nhật qua WebSocket, và **lane** (làn đường) theo dõi công việc song song của agent qua một pipeline. Internal build — all rights reserved. *(Bản dịch tiếng Việt của [README.md](README.md), tham khảo — README.md gốc là bản chính thức.)* ## Làm được gì - **Session, agent, event.** Mọi thứ Claude Code emit ra, ghi lại và tìm kiếm được: tool call, token usage, cost, cây subagent, transcript. - **Lane.** Mỗi working directory một lane, sống sót qua session restart. Lane đi qua các pipeline stage và dashboard hiển thị nó đang ở đâu. - **Stage detection.** Stage được suy luận (infer) từ tool stream, nên một session không bao giờ gọi `ccam stage` vẫn hiển thị progress — render dạng viền chấm màu hổ phách (amber) và không bao giờ hiện `done`, vì suy luận không phải bằng chứng. - **Chạy Claude từ trình duyệt.** Spawn session trong thư mục của lane, stream output, gửi follow-up, resume session cũ bất kỳ. - **Analytics, alert, Kanban và workflow view**, cộng thêm MCP server và CLI. ## Yêu cầu Node **>= 20** (`engines` trong `package.json`). Node **24** là bản test suite được verify — node 25 hiện đang làm gãy 6 test server do lệch ABI `better-sqlite3` và 20 test client do thay đổi global `localStorage`. ## Cài như Claude Code plugin Hai lệnh, trên máy chỉ có Claude Code, không cần clone repo, không cần `npm run setup`: ``` /plugin marketplace add Smartgift-AI/Claude-Code-Monitor /plugin install ccam@claude-code-agent-monitor-plugins ``` Lần session-start đầu tiên sẽ cài hooks, boot server, đưa `ccam` vào PATH và kết nối MCP tools; chạy detached nên session không phải chờ. `/ccam-doctor` báo trạng thái, `/ccam-open` build UI và in URL, `/ccam-update` refresh sau khi plugin update. Đường này cần Node **>= 22.5** (không dùng `better-sqlite3` native, server dùng `node:sqlite`). Chi tiết, kể cả những gì cần xóa lúc uninstall: [`docs/PLUGINS.md`](docs/PLUGINS.md). ## Cài từ checkout ```bash npm run setup # cài dependency cho root, client và vscode-extension npm run build # build client vào client/dist npm start # serve client đã build + API trên :4820 ``` Mở . Development, có hot reload: ```bash npm run dev # server trên :4820, Vite client trên :5173 ``` `DASHBOARD_PORT` override port, `DASHBOARD_CLIENT_DIST` override nơi UI đã build được serve (mặc định `client/dist`; bản cài qua plugin trỏ vào runtime directory riêng của nó). `postinstall` ghi các hook entry Claude Code để nạp dữ liệu cho dashboard — đừng chạy nó khi plugin `ccam` đã cài, không thì mỗi event bị đếm hai lần. ## CLI `ccam` được link sẵn bởi `npm run setup`; không thì gọi `node bin/ccam.js`. ```bash ccam status # dashboard có đang chạy không ccam start # start ngầm (background) và chờ tới khi healthy ccam sessions # session gần đây ccam lanes # danh sách lane kèm stage và progress ccam lanes pipeline # pipeline template của lane này, hoặc đổi nó ccam stage # khai báo stage hiện tại của lane ccam tail # xem live event feed ``` `ccam --help` liệt kê phần còn lại. ## Lane Lane là một working directory mà dashboard theo dõi. Hai loại: - **adopted** (nhận nuôi) — một thư mục bạn đã có sẵn. Dashboard chỉ đọc nó; không bao giờ reset hay xóa. - **managed** (tự quản lý) — git worktree do dashboard tạo dưới `LANES_ROOT`. Dashboard sở hữu toàn bộ vòng đời và có thể reset/xóa nó, phía sau một guard ba lớp kiểm tra khi hủy (destroy guard) và một bước preflight đếm số mà bên gọi phải echo lại. ```bash ccam lanes add --cwd /path/to/repo --title "My feature" # adopt ccam lanes add --repo /path/to/repo --slug my-feature # managed worktree ``` Stage khai báo (declared) đến từ `ccam stage`. Stage suy luận (inferred) đến từ tool event và hết hạn sau `DETECTION_TTL_MS` (mặc định 5 phút), nên lane có thể lùi lại giữa các work session. Detection không bao giờ ghi đè stage khai báo, và node suy luận không bao giờ render thành `done`. Pipeline template của lane có thể đổi sau khi tạo — `ccam lanes pipeline