# 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.)*

## 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**

- **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. **Đâ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 lane.** Repo khai báo `.agenthub/profile/` thì mỗi
  lane được cấp slot, port và service riêng (`agenthub lanes up|down|logs`).
- **Ship pipeline.** `/agenthub:ship-full` và `/agenthub:ship-quick` đưa một
  feature từ intake tới PR, khai báo từng stage về dashboard trên đường đi.

**Cấu hình**

- **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 lane (worktree, đọc branch/status) |
| **tmux** | 3.x | Run console trên trình duyệt, `agenthub lanes 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 lane dùng `codex` |
| **GitHub CLI (`gh`)** | bất kỳ | Tùy chọn — chỉ cho `agenthub lanes ci status` và các stage PR của ship pipeline |
| **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 lanes shell` sẽ lỗi. Phần còn lại (session,
analytics, lane, 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 lane chạy trong một tmux session tên `agenthub-lane-<id>`, nên terminal
trên trình duyệt và `tmux attach -t agenthub-lane-<id>` (hoặc `agenthub lanes
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`.

### Plugin superpowers

Plugin **`superpowers` chỉ cần cho ship-feature pipeline**, không cần cho
dashboard. `/agenthub:ship-feature` và `/agenthub:ship-feature-lane` lái các skill
của nó theo từng phase. Thiếu nó thì dashboard, hook và CLI vẫn chạy bình thường
— chỉ hai skill pipeline là dừng giữa chừng; `/agenthub-doctor` báo dòng `WARN`.

**Bình thường bạn không phải tự cài.** Bootstrap `SessionStart` của plugin cài
giúp một lần trong worker chạy nền, và session hiện tại cần `/reload-plugins`
thì skill mới resolve được (session sau tự nhận). Cài tay:

```bash
claude plugin install superpowers@claude-plugins-official
```

Đặt `AGENTHUB_AUTO_INSTALL_PLUGINS=0` để tắt cài tự động.

## 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`](docs/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ở <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 `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 <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](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 <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.

```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.
Lane 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).

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ừ đó:

```bash
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`](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/agenthub.js` | CLI |
| `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