nntrivi2001
c7dbaf2d9f
Two leftovers from the rebrand, done together because they touch the same docs and manifests. **Data directory.** `agent-dashboard` could not simply be renamed in the source: it names a real directory holding the live SQLite database. Startup now moves it once, via `migrateLegacyDataDir()` in `server/lib/claude-home.js` — a same-filesystem rename, so it is instant even at multiple gigabytes and cannot leave two divergent copies. `getDataDir()` stays PURE and resolves to the legacy path until the move happens; the first version of this put the rename inside the getter, which meant `npm run test:server` relocated the developer's real database as a side effect. The call sits behind `require.main === module` and ahead of the router requires, because those pull in db.js, which opens SQLite at module load. A failed rename is silent and the old directory keeps being used: an unfashionable directory name beats a blank database beside an unreachable one. Same treatment for the port-discovery file (`.agent-dashboard.json` → `.agenthub.json`, old one dropped on write). Not renamed on purpose: the Sagi localStorage keys (renaming silently resets everyone's prefs) and the PWA manifest `id` (changing it orphans an installed app). **MCP server.** 4 tool calls in 46 days across 577,132 events, against 4,556 lines of TypeScript, a 2 MB committed build artifact, and a pre-commit guard that had already blocked commits twice. Deleted: `mcp/`, the maintainer skills and `mcp-reviewer` agent, the build check, `plugins/agenthub/.mcp.json`, `docs/MCP.md`, 12 npm scripts, 5 Makefile targets, and every doc section describing it. Kept, because they are unrelated things sharing the name: the Config Explorer's MCP tab and its API, per-lane Playwright MCP, the agenthub-config plugin's MCP audit, and the historical `mcp__plugin_agenthub_*` events that analytics must keep attributing. Verified: server 1432/1432, client 459/459, tsc clean, prettier clean. Both directions of the migration proven — a sandbox-HOME test run leaves the legacy directory untouched, and a real boot moves it with its contents intact.
9.8 KiB
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, 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 stagevẫn hiển thị progress — render dạng viền chấm màu hổ phách (amber) và không bao giờ hiệndone, 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.
Cài từ checkout
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
Development, có hot reload:
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:
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 <user> để 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 trong
docs/PLUGINS.md.
CLI
agenthub được link sẵn bởi npm run setup; không thì gọi node bin/agenthub.js.
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 <id> # 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 <name> # 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.
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 <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>/.agenthub/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ừ đó:
agenthub lanes up # boot stack của lane sở hữu thư mục hiện tại
agenthub lanes runtime # slot, port, tình trạng service
agenthub lanes logs api # tail log của một service
agenthub 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 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
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/agenthub.js |
CLI |
docs/ |
Architecture, API, lanes, database |
plugins/ |
Các Claude Code plugin đi kèm dashboard |
Tài liệu
ARCHITECTURE.md— luồng request, schema, bề mặt WebSocketdocs/LANES.md— lane, pipeline, stage detectiondocs/API.md— REST endpoint (openapi.yamlđược generate tự động)docs/DATABASE.md— bảng và migrationINSTALL.mdCLAUDE.md— quy tắc agent làm việc trong repo này phải tuân theo