# Tham Khảo Nhanh Herdr

*Workspaces, panes, trạng thái agent, tự động hóa CLI (v0.9.x)*

> Source: Herdr documentation (herdr.dev, v0.9.3) and herdr CLI help output · MIT

## Mô Hình Tư Duy

### Các Lớp

| Command | Description |
|---------|-------------|
| `session` | Namespace server nền; sở hữu mọi tiến trình |
| `workspace` | Mỗi repo hoặc tác vụ một cái; sidebar gộp trạng thái agent |
| `tab` | Một bố cục trong workspace (agents, logs, server) |
| `pane` | Terminal thật; chia phải hoặc dưới, sống sót khi detach |
| `agent` | Coding agent mà Herdr nhận diện trong một pane |

*Detach client thì server và mọi pane vẫn chạy*

### Trạng Thái Agent

| Command | Description |
|---------|-------------|
| `working` | Agent đang bận xử lý một lượt |
| `blocked` | Chờ prompt phê duyệt hoặc một câu hỏi |
| `done` | Đã xong, bạn chưa xem |
| `idle` | Đã xong hoặc đang chờ, đã xem |
| `unknown` | Có agent, trạng thái chưa rõ; không chắc đã xong |

*idle và done đều nghĩa là agent sẵn sàng nhận prompt mới*

### Chế Độ Nhập

| Command | Description |
|---------|-------------|
| `terminal` | Phím đi thẳng vào pane đang focus |
| `prefix` | Sau Ctrl-b, phím kế tiếp là hành động Herdr |
| `navigate` | Giao diện điều hướng workspace cố định |
| `copy` | Scrollback bằng bàn phím, tìm và chọn (Prefix [) |

## Bắt Đầu

### Cài Đặt & Khởi Chạy

```
curl -fsSL https://herdr.dev/install.sh | sh
cd ~/projects/app
herdr           # launch or attach
claude          # any agent, auto-detected
herdr update    # self-update
herdr status    # client vs server version
```

### Tích Hợp Agent

```
herdr integration install claude
herdr integration install codex
herdr integration status --outdated-only
```

*Tích hợp báo trạng thái chính xác và cho agent tiếp tục sau khi server khởi động lại*

### Ưu Tiên Chuột

> Mọi thứ đều nhấp được: pane, tab, workspace, dòng agent. Kéo viền để đổi kích thước, chuột phải để mở menu chia và tab, kéo chọn để sao chép. Phím tắt chỉ là lớp tùy chọn bên trên.

## Phím Tắt

### Học Trước Tiên

| Command | Description |
|---------|-------------|
| `Prefix ?` | Hiện mọi binding đang dùng (/ để lọc) |
| `Prefix c` | Tab mới |
| `Prefix v` | Chia: pane mới bên phải |
| `Prefix -` | Chia: pane mới bên dưới |
| `Prefix h/j/k/l` | Focus pane trái / dưới / trên / phải |
| `Prefix w` | Điều hướng workspace |
| `Prefix q` | Detach; mọi thứ vẫn chạy |

*Prefix mặc định là Ctrl-b. Detach là q, không phải d như tmux*

### Panes

| Command | Description |
|---------|-------------|
| `Prefix z` | Zoom (toàn màn hình) pane đang focus |
| `Prefix x` | Đóng pane |
| `Prefix Shift-h/j/k/l` | Hoán đổi pane với pane kế bên |
| `Prefix r` | Chế độ đổi kích thước |
| `Prefix Tab` | Chuyển sang pane tiếp theo |
| `Prefix Shift-p` | Đổi tên pane |
| `Prefix e` | Mở scrollback trong editor |

### Tabs & Workspaces

| Command | Description |
|---------|-------------|
| `Prefix n / p` | Tab tiếp theo / trước |
| `Prefix 1..9` | Nhảy đến tab theo số |
| `Prefix Shift-t / Shift-x` | Đổi tên / đóng tab |
| `Prefix Shift-n` | Workspace mới |
| `Prefix Shift-g` | Workspace mới trên git worktree |
| `Prefix Shift-w / Shift-d` | Đổi tên / đóng workspace |
| `Prefix g` | Bộ chọn Goto: mọi agent và terminal |
| `Prefix o` | Nhảy đến pane của thông báo mới nhất |
| `Prefix b` | Bật/tắt sidebar |
| `Prefix s` | Cài đặt |

*Trong bộ chọn Goto, b/w/i/d lọc blocked/working/idle/done; / để tìm*

### Copy Mode (Prefix [)

| Command | Description |
|---------|-------------|
| `h/j/k/l  w/b/e` | Di chuyển theo ký tự hoặc từ |
| `Ctrl-u / Ctrl-d` | Lên / xuống nửa trang |
| `/  ?  n  N` | Tìm tiến / lùi, lặp lại |
| `v or Space` | Bắt đầu chọn |
| `y or Enter` | Sao chép vùng chọn và thoát |
| `q or Esc` | Thoát không sao chép |

*Pane vẫn chạy trong khi bạn cuộn scrollback*

## Sessions & Từ Xa

### Duy Trì

```
herdr                      # reattach
herdr session list
herdr session attach work  # isolated server
herdr session stop work
herdr server stop          # kills ALL panes
```

### Qua SSH

```
herdr --remote workbox  # local UI, remote panes
herdr --remote workbox --session agents
herdr machine add workbox --label box
herdr --machine box agent list
```

### Workspace Dạng Worktree

```
herdr worktree create --branch fix/login --base main
herdr worktree list
herdr worktree remove --workspace w3
```

## Scripting Panes

### ID & Ngữ Cảnh

> ID có dạng w1 (workspace), w1:t1 (tab), w1:p1 (pane). Trong một pane Herdr, HERDR_ENV=1 và HERDR_PANE_ID được đặt sẵn. Lệnh trả về JSON: đọc ID mới từ phản hồi, đừng đoán theo thứ tự sidebar.

### Khám Phá

```
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr pane layout --current
```

### Chạy Lệnh Ở Pane Bên Cạnh

```
id=$(herdr pane split --current \
       --direction right --no-focus \
     | jq -r .result.pane.pane_id)
herdr pane run "$id" "npm test"
herdr pane wait-output "$id" \
  --match "passed" --timeout 120000
herdr pane read "$id" --lines 80 \
  --source recent-unwrapped
```

### Lệnh Pane

| Command | Description |
|---------|-------------|
| `pane run ID CMD` | Gõ lệnh và nhấn Enter trong một bước |
| `pane send-text ID TEXT` | Gõ văn bản nguyên văn, không Enter |
| `pane send-keys ID ctrl+c` | Gửi phím theo tên |
| `pane wait-output --regex RE` | Chờ đến khi đầu ra khớp (Rust regex) |
| `pane zoom ID --toggle` | Zoom pane từ script |
| `pane move ID --new-tab` | Di chuyển pane; pane nhận ID mới |
| `notification show TITLE` | Hiện toast, tùy chọn kèm --sound done |

## Điều Phối Agent

### Khởi Động, Prompt, Thu Kết Quả

```
herdr agent start reviewer --kind codex --pane "$id"
herdr agent prompt reviewer "Review the diff" \
  --wait --timeout 300000
herdr agent read reviewer --lines 120
herdr agent wait reviewer --until blocked
herdr agent send-keys reviewer esc
```

### Lệnh Agent

| Command | Description |
|---------|-------------|
| `agent list` | Mọi agent đang chạy kèm trạng thái |
| `agent get NAME` | Pane, loại và trạng thái của một agent |
| `agent focus NAME` | Nhảy UI đến agent đó (đánh dấu đã xem) |
| `agent attach NAME` | Chỉ mở terminal đó, không có UI Herdr |
| `agent explain NAME` | Vì sao bộ nhận diện chọn trạng thái này |

*Đích là tên agent duy nhất hoặc ID pane chứa nó*

### Lệnh Pane và Lệnh Agent

| Choice | Use when | Watch for |
|--------|----------|-----------|
| `pane` | Shell, test, server | Không biết trạng thái agent |
| `agent` | Coding agent đã được nhận diện | Từ chối agent đang blocked |

### Nguyên Tắc Kinh Nghiệm

> agent start cần một pane có sẵn đang ở shell prompt; nó không bao giờ tạo bố cục. Dùng --no-focus cho việc chạy nền. Sau timeout, đọc agent trước khi gửi lại: prompt có thể đã được nhận.

## Cấu Hình

### ~/.config/herdr/config.toml

```
[keys]
prefix = "ctrl+a"
focus_pane_left = ["prefix+h", "ctrl+alt+h"]
[theme]
name = "tokyo-night"
[ui.toast]
delivery = "system"  # or herdr / terminal
```

### Lệnh Popup Tùy Chỉnh

```
[[keys.command]]
key = "prefix+alt+g"
type = "popup"       # or "pane" / "shell"
command = "lazygit"
width = "80%"
height = "80%"
```

### Lệnh Cấu Hình

| Command | Description |
|---------|-------------|
| `herdr --default-config` | In mọi tùy chọn kèm chú thích |
| `herdr config check` | Kiểm tra config.toml |
| `Prefix Shift-r` | Tải lại cấu hình trong server đang chạy |
| `herdr config reset-keys` | Sao lưu cấu hình, bỏ binding tùy chỉnh |

*Tổ hợp ctrl+alt là binding không cần prefix an toàn nhất trên mọi terminal*