# AgentHub Bản build nội bộ SmartGift. **Bàn điều khiển** local-first cho agent Claude Code — monitoring chỉ là một phần, không phải tất cả. Hooks POST mỗi tool call lên server Express + SQLite và React UI cập nhật qua WebSocket; **lane** (làn đường) theo dõi công việc song song của agent qua một pipeline; còn CLI `agenthub` điều khiển phiên terminal thật, runtime của lane, và cả cấu hình của chính Claude Code. AgentHub ghi nhận và trình bày — nó không điều phối. Phiên đang chạy mới là nơi ra mọi quyết định. 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 `agenthub 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 Code hoặc Codex từ trình duyệt.** Một terminal thật (tmux + PTY thật, render bằng xterm.js) gắn vào thư mục của lane — đúng cái TUI bạn thấy ở máy, tương tác đầy đủ, resume được, và attach được từ terminal thật qua `agenthub lanes shell`. Chạy CLI nào là thiết lập riêng của từng lane. - **Analytics (tab trong dashboard), alert và workflow view**, cộng thêm 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 agenthub@claude-code-agent-monitor-plugins ``` Lần session-start đầu tiên sẽ cài hooks, boot server, đưa `agenthub` vào PATH và chạy detached nên session không phải chờ. `/agenthub-doctor` báo trạng thái, `/agenthub-open` build UI và in URL, `/agenthub-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 `agenthub` đã cài, không thì mỗi event bị đếm hai lần. ### Chạy như một service (tự khởi động khi boot máy) `npm start` chỉ chạy khi terminal đó (hoặc tiến trình nền của `agenthub start`) còn sống — reboot máy là mất. Trên Linux, `agenthub service install` dựng một systemd `--user` service thay vào đó, để `:4820` tự động chạy lại sau mỗi lần reboot, không cần thao tác thủ công và không cần Claude Code (hay AI tool nào) để kích hoạt: ```bash npm run build # service serve client đã build, giống npm start agenthub service install # ghi + enable ~/.config/systemd/user/agenthub.service agenthub service status # systemctl --user status agenthub agenthub service uninstall # disable và gỡ bỏ ``` `agenthub service install` cũng thử chạy `loginctl enable-linger` để service khởi động được cả khi cold boot (chưa ai login); nếu máy cần quyền cao hơn, lệnh này sẽ in ra `sudo loginctl enable-linger ` để bạn tự chạy một lần. Bản cài qua plugin cũng được tự khởi động tương tự — xem [Auto-start on boot](docs/PLUGINS.md#auto-start-on-boot) trong `docs/PLUGINS.md`. ## CLI `agenthub` được link sẵn bởi `npm run setup`; không thì gọi `node bin/agenthub.js`. ```bash agenthub status # dashboard có đang chạy không agenthub start # start ngầm (background) và chờ tới khi healthy agenthub service install # tự khởi động khi boot máy qua systemd --user (Linux) agenthub sessions # session gần đây agenthub lanes # danh sách lane kèm stage và progress agenthub lanes pipeline # pipeline template của lane này, hoặc đổi nó agenthub lanes node # chạy riêng command của MỘT node (không có id: liệt kê) # (trong session: /intake, /qc, /ship-full, /ship-quick …) agenthub stage # khai báo stage hiện tại của lane agenthub tail # xem live event feed ``` `agenthub --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 agenthub lanes add --cwd /path/to/repo --title "My feature" # adopt agenthub lanes add --repo /path/to/repo --slug my-feature # managed worktree ``` Mỗi lane còn mang theo CLI điều khiển nó — `claude` (mặc định) hoặc `codex` — chọn trong modal Add lane và cố định suốt vòng đời của lane. Lane Codex có panel chạy với các lựa chọn riêng của Codex (sandbox, approval, reasoning effort) và resume bằng `codex resume --last`. Codex không bắn hook của dashboard này, nên lane Codex vẫn ghi lịch sử chạy nhưng không xuất hiện ở Sessions và Analytics. **Stage detection thì vẫn chạy**, đọc từ rollout journal của chính Codex trên đĩa (`$CODEX_HOME/sessions/**/rollout-*.jsonl`, poll mỗi `DASHBOARD_CODEX_POLL_MS` ms, mặc định 15000) — thứ lane Codex không tự có là stage **khai báo**, vì chỉ chính session đó mới gọi được `agenthub stage`. Stage khai báo (declared) đến từ `agenthub 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 — `agenthub lanes pipeline