# 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; **workspace** theo dõi công việc song song của agent, mỗi working directory một workspace; còn CLI `agenthub` điều khiển phiên terminal thật, runtime của workspace, 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 [OVERVIEW.md](OVERVIEW.md), tham khảo — OVERVIEW.md gốc là bản chính thức.)* ## Chức năng chính **Quan sát** - **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. - **Analytics và chi phí.** Token và cost ước tính theo từng model, với bảng pricing sửa được; top tool, agent type và workflow pattern. - **Activity feed và alert.** Luồng event trực tiếp, alert rule, và webhook target bắn khi rule khớp. - **Import lịch sử.** Mọi session dưới `~/.claude/projects/` được import lúc khởi động; lịch sử từ máy khác đưa vào qua Settings → Import History (idempotent, không bao giờ đếm trùng token). - **Remote source.** Kéo lịch sử session từ máy khác qua SSH (`agenthub remote-sources`). **Điều khiển** - **Workspace.** Mỗi working directory một workspace, sống sót qua session restart. Khi bạn cài một pipeline template (không có template nào đi kèm), workspace đi qua các stage của nó và dashboard hiển thị nó đang ở đâu. - **Stage detection.** Khi đã cài template, 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 workspace — đú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 workspace shell`. Chạy CLI nào là thiết lập riêng của từng workspace. **Đây chính là phần cần cài `tmux`** — xem [Yêu cầu hệ thống](#yêu-cầu-hệ-thống). - **App stack riêng cho từng workspace.** Repo khai báo `.agenthub/profile/` thì mỗi workspace được cấp slot, port và service riêng (`agenthub workspace up|down|logs`). **Cấu hình** - **Workspace như project của Claude Desktop.** Sidebar liệt kê mọi workspace kèm các session của nó (session còn sống mở đúng tmux pane, session khác mở transcript — không bao giờ resume). Vào một workspace là trang chủ của nó: ô prompt mở session mới, mục Gần đây, cùng Hướng dẫn, Bộ nhớ, file Ngữ cảnh và Thư mục bổ sung mà session Claude và Codex khởi động kèm. - **Settings mỗi mục một trang** (`/settings/
`): thanh điều hướng bên trái chia nhóm Chung / Tác tử / Định tuyến / Git, ô tìm kiếm (Ctrl+F) trên mọi mục, một trang cho mỗi AI tool đã cài, bảng giá mô hình theo nhà cung cấp, và những worktree chưa theo dõi được gợi ý khi thêm thư mục cho workspace. - **Trình khám phá cấu hình Claude Code + Codex.** Trang Settings có một panel cho mỗi tool: mọi plugin, skill, subagent, slash command, MCP server, hook, settings file, memory file, marketplace, keybinding và statusline mà Claude Code biết — đọc được tất cả, còn sửa/tạo/xóa thì chỉ cho các bề mặt dạng file text (skill, agent, command, output style, `CLAUDE.md`). Plugin, MCP, hook và `settings.json` để read-only: chúng tranh ghi với CLI đang chạy. - **Cập nhật.** Phát hiện bản mới dựa trên release, kèm nút **Update all** ngay trong UI (marketplace → mọi plugin → AgentHub sau cùng → reload session). - **CLI cho toàn bộ** (`agenthub`, và `agenthub repl`), cài được như PWA, UI có tiếng Anh, Việt, Trung và Hàn. ## Yêu cầu hệ thống | Cần | Phiên bản | Dùng cho | |---|---|---| | **Node.js** | >= 20 (>= 22.5 nếu cài qua plugin) | Tất cả. Cả hai test suite verify xanh trên Node **24** và **26** | | **npm** | 9+ | Đi kèm Node | | **git** | bất kỳ | Clone repo, và mọi thao tác workspace (worktree, đọc branch/status) | | **tmux** | 3.x | Run console trên trình duyệt, `agenthub workspace shell`, gõ `/reload-plugins` vào pane đang sống | | **Claude Code** | 2.x | Hook ingestion — toàn bộ phần monitoring | | **Codex CLI** | bất kỳ | Tùy chọn — chỉ cho workspace dùng `codex` | | **GitHub CLI (`gh`)** | bất kỳ | Tùy chọn — chỉ cho `agenthub workspace ci status` | | **systemd (user)** | — | Tùy chọn — chỉ cho `agenthub service install` (tự khởi động khi boot, Linux) | Node **25** là bản duy nhất nên tránh: nó làm gãy 6 test server do lệch ABI `better-sqlite3` và 20 test client do thay đổi global `localStorage`. Tới 26 thì cả hai đã hết (1712 test server + 488 test client xanh trên v26.8.1). ### Cài tmux Dashboard gọi thẳng binary `tmux`, không có bản dự phòng đi kèm, nên thiếu nó thì **Start Run** và `agenthub workspace shell` sẽ lỗi. Phần còn lại (session, analytics, workspace, stage detection, CLI) vẫn chạy bình thường. ```bash sudo apt install tmux # Debian / Ubuntu sudo dnf install tmux # Fedora / RHEL brew install tmux # macOS sudo pacman -S tmux # Arch ``` Windows không có tmux native — chạy AgentHub trong WSL2 và cài tmux ở trong đó. macOS (đã rà soát code, chưa kiểm thử trên máy Mac): `brew install node git tmux` (Node >= 22.5 cho bản plugin), thêm `~/.local/bin` vào `PATH` trong `~/.zshrc`. Không có systemd, nên dashboard chạy đến khi đăng xuất/khởi động lại và tự lên lại ở phiên Claude Code kế tiếp, hoặc chạy tay bằng `agenthub start`. Chi tiết và checklist kiểm tra: [INSTALL.md § macOS](../INSTALL.md#macos). Kiểm tra, cả từ shell của bạn lẫn từ góc nhìn của server: ```bash tmux -V # ví dụ: tmux 3.4 curl -s localhost:4820/api/run/tmux # {"available":true} ``` Mỗi workspace chạy trong một tmux session tên `agenthub-lane-`, nên terminal trên trình duyệt và `tmux attach -t agenthub-lane-` (hoặc `agenthub workspace shell`) ở máy là hai client trên cùng một pane — chúng đồng bộ với nhau, và tắt dashboard không bao giờ giết run đang chạy. Detach bằng `Ctrl-b d`. ## 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 https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git /plugin install agenthub@agenthub ``` 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`](PLUGINS.md). ## Cài từ checkout ```bash npm run setup # cài dependency cho root và client 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. Trong dashboard cũng có công tắc tương ứng — Settings → Hệ thống → **Tự động khởi động AgentHub** (mặc định tắt; chỉ enable/disable unit, không bao giờ dừng server đang chạy). Bản cài qua plugin chỉ được tự khởi động khi công tắc này bật — xem [Auto-start on boot](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 workspaces # danh sách workspace kèm stage và progress agenthub workspace pipeline # pipeline template của lane này, hoặc đổi nó agenthub workspace node # chạy riêng command của MỘT node (không có id: liệt kê) 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. ## Workspace Workspace 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 workspace add --cwd /path/to/repo --title "My feature" # adopt agenthub workspace add --repo /path/to/repo --slug my-feature # managed worktree ``` Mỗi workspace còn mang theo CLI điều khiển nó — `claude` (mặc định) hoặc `codex` — chọn trong modal Add workspace và cố định suốt vòng đời của workspace. Workspace 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 workspace Codex vẫn ghi lịch sử chạy nhưng không xuất hiện ở Sessions và Analytics. Workspace Codex cũng **không có pipeline** — không stage, không pipeline map, không suy luận hay tự nhảy stage; dashboard chỉ phản ánh trạng thái running/idle 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). **Pipeline đang tạm ngưng (dormant).** AgentHub không đi kèm pipeline template nào, nên workspace không có stage cho tới khi bạn thả một file template JSON vào `DASHBOARD_PIPELINES_DIR` (xem [`docs/LANES.md`](LANES.md#custom-pipeline-templates)); trước đó `agenthub stage` trả về `ENOPIPELINE` và trang Workspace ẩn pipeline map. Phần này sẽ được phát triển tiếp. 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 workspace 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 workspace có thể đổi sau khi tạo — `agenthub workspace pipeline