# 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ở <http://localhost:4820>.

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 <name>        # 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 <template>` từ terminal, hoặc dùng picker chọn pipeline-template
cạnh tiêu đề lane trong panel chi tiết của trang Workspace. Cả hai đều
re-resolve lại stage đã khai báo hiện tại của lane theo node-list của template
mới, và cảnh báo nếu nó không còn khớp node nào.

Lane cũng có thể chạy **application stack riêng của nó**, cô lập theo từng
lane, khi repository của nó khai báo một profile tại `<repo>/.ccam/profile/`
— một file `profile.env` khai báo cộng shell hooks mà dashboard gọi. Mỗi lane
được cấp một slot, port và thư mục riêng theo lane được suy ra từ đó:

```bash
ccam lanes up            # boot stack của lane sở hữu thư mục hiện tại
ccam lanes runtime       # slot, port, tình trạng service
ccam lanes logs api      # tail log của một service
ccam lanes down
```

Service chạy hoàn toàn detached, nên restart dashboard không bao giờ dừng
lane đang chạy. Đây là namespacing tài nguyên trên host, không phải
container: các lane chạy chung user và share network.

[`docs/LANES.md`](docs/LANES.md) có mô hình pipeline, destroy guard, hợp đồng
(contract) preflight, trang Workspace, `GET /api/lanes/:id/git`, và toàn bộ
hợp đồng runtime/profile.

## Test

```bash
npm run test:server    # node:test
npm run test:client    # Vitest
```

Cả hai phải xanh (pass) trước khi commit; pre-commit hook chạy chúng cộng
thêm Prettier.

## Cấu trúc thư mục

| Đường dẫn | Là gì |
|---|---|
| `server/` | Express API, schema SQLite, hook ingest, thư viện lane và worktree |
| `client/` | Dashboard React 18 + Vite + Tailwind |
| `bin/ccam.js` | CLI |
| `mcp/` | MCP server expose các tool đọc dữ liệu dashboard (read-only) |
| `docs/` | Architecture, API, lanes, database |
| `plugins/` | Các Claude Code plugin đi kèm dashboard |

## Tài liệu

- [`ARCHITECTURE.md`](ARCHITECTURE.md) — luồng request, schema, bề mặt WebSocket
- [`docs/LANES.md`](docs/LANES.md) — lane, pipeline, stage detection
- [`docs/API.md`](docs/API.md) — REST endpoint (`openapi.yaml` được generate tự động)
- [`docs/DATABASE.md`](docs/DATABASE.md) — bảng và migration
- [`INSTALL.md`](INSTALL.md)
- [`CLAUDE.md`](CLAUDE.md) — quy tắc agent làm việc trong repo này phải tuân theo
