docs: document terminal core in next docs
This commit is contained in:
Ogulcan Celik
parent
f7fe0f203e
commit
c115dbd051
|
|
@ -108,12 +108,6 @@ Host workbox
|
|||
|
||||
same session, same agents, same state.
|
||||
|
||||
### direct agent attach
|
||||
|
||||
`herdr` and `herdr --remote` attach to the full Herdr session UI. `herdr agent attach <target>` attaches your current terminal directly to one server-owned terminal, like a single-pane terminal attach. `herdr terminal attach <terminal_id>` does the same by terminal id.
|
||||
|
||||
Direct attach streams the current rendered terminal state first, then live ANSI frames. Your input goes straight to that terminal. Detach with `ctrl+b q`; send a literal `ctrl+b` with `ctrl+b ctrl+b`. One writable client owns input and resize for a terminal. A second attach fails unless you pass `--takeover`.
|
||||
|
||||
## agent awareness
|
||||
|
||||
the sidebar shows which agents are blocked, working, or done. workspaces roll up to their most urgent state so you can scan the full list at a glance.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ if you are teaching an agent that is already running inside herdr, start with [`
|
|||
there are three practical ways to integrate with herdr:
|
||||
|
||||
- **agent skill** — [`SKILL.md`](./SKILL.md). best when an agent inside herdr just needs to learn the workflow quickly.
|
||||
- **cli wrappers** — `herdr server stop`, `herdr workspace ...`, `herdr tab ...`, `herdr agent ...`, `herdr pane ...`, `herdr wait ...`. best for shell scripts and simple orchestration.
|
||||
- **cli wrappers** — `herdr server stop`, `herdr workspace ...`, `herdr tab ...`, `herdr pane ...`, `herdr wait ...`. best for shell scripts and simple orchestration.
|
||||
- **raw socket api** — best when you want direct request/response control or long-lived event subscriptions.
|
||||
|
||||
these layers are intentionally stacked on top of the same control surface.
|
||||
|
|
@ -141,7 +141,6 @@ for backward compatibility, requests also accept the older positional forms like
|
|||
```json
|
||||
{
|
||||
"pane_id": "w64e95948145ed1-1",
|
||||
"terminal_id": "term_64e95948145ed1",
|
||||
"workspace_id": "w64e95948145ed1",
|
||||
"tab_id": "w64e95948145ed1:1",
|
||||
"focused": true,
|
||||
|
|
@ -153,29 +152,8 @@ for backward compatibility, requests also accept the older positional forms like
|
|||
}
|
||||
```
|
||||
|
||||
`terminal_id` is an opaque terminal identity. during the pane-backed transition each pane has one terminal id, but clients should not derive it from the pane id.
|
||||
|
||||
`label` is an optional manual pane name set through `pane.rename`.
|
||||
|
||||
`agent_info` responses contain a terminal-facing view of the same live pane-backed terminal:
|
||||
|
||||
```json
|
||||
{
|
||||
"terminal_id": "term_64e95948145ed1",
|
||||
"name": "reviewer",
|
||||
"agent": "pi",
|
||||
"agent_status": "working",
|
||||
"workspace_id": "w64e95948145ed1",
|
||||
"tab_id": "w64e95948145ed1:1",
|
||||
"pane_id": "w64e95948145ed1-1",
|
||||
"focused": true,
|
||||
"cwd": "/home/can/Projects/herdr",
|
||||
"revision": 0
|
||||
}
|
||||
```
|
||||
|
||||
`name` is the manual pane label treated as the terminal/agent name by `agent.*` commands. `agent.rename` rejects duplicate active names; `pane.rename` remains backward-compatible and can still create duplicates.
|
||||
|
||||
`agent` is an optional display label string.
|
||||
|
||||
- when herdr detects a built-in agent, this is that built-in name like `pi` or `claude`
|
||||
|
|
@ -225,13 +203,6 @@ for backward compatibility, requests also accept the older positional forms like
|
|||
| `tab.focus` | focus a tab | `tab_info` |
|
||||
| `tab.rename` | rename a tab | `tab_info` |
|
||||
| `tab.close` | close a tab | `ok` |
|
||||
| `agent.list` | list named or detected terminal-backed agents | `agent_list` |
|
||||
| `agent.get` | inspect one terminal-backed agent by terminal id, unique name, or pane id | `agent_info` |
|
||||
| `agent.read` | read output from one terminal-backed agent | `pane_read` |
|
||||
| `agent.send` | send literal text to one terminal-backed agent | `ok` |
|
||||
| `agent.rename` | set or clear the unique agent/terminal name | `agent_info` |
|
||||
| `agent.focus` | show the terminal-backed agent in the TUI | `agent_info` |
|
||||
| `agent.start` | start a named terminal-backed agent from argv | `agent_started` |
|
||||
| `pane.list` | list panes, optionally filtered by workspace | `pane_list` |
|
||||
| `pane.get` | inspect one pane | `pane_info` |
|
||||
| `pane.rename` | set or clear a manual pane label | `pane_info` |
|
||||
|
|
@ -989,20 +960,6 @@ herdr tab rename <tab_id> <label>
|
|||
herdr tab close <tab_id>
|
||||
```
|
||||
|
||||
agent commands:
|
||||
|
||||
```text
|
||||
herdr agent list
|
||||
herdr agent get <target>
|
||||
herdr agent read <target> [--source visible|recent|recent-unwrapped] [--lines N] [--format text|ansi] [--ansi]
|
||||
herdr agent send <target> <text>
|
||||
herdr agent rename <target> <name>|--clear
|
||||
herdr agent focus <target>
|
||||
herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--focus|--no-focus] -- <argv...>
|
||||
```
|
||||
|
||||
agent targets accept terminal ids, unique agent names, and legacy pane ids. duplicate names fail clearly for `agent.*`; `pane.rename` can still create duplicate pane labels for backward compatibility. `agent start` treats everything after `--` as argv and does not require agent-specific launch logic.
|
||||
|
||||
pane commands:
|
||||
|
||||
```text
|
||||
|
|
@ -1037,10 +994,6 @@ herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [
|
|||
- `tab create` without `--label` keeps the default numbered tab naming
|
||||
- `tab create --label` applies the custom tab name immediately
|
||||
- `tab create` returns `result.tab` and `result.root_pane`
|
||||
- `agent list` shows named panes and detected/reported agents as terminal-backed agents
|
||||
- `agent focus` switches the TUI workspace/tab/pane focus; it is not direct terminal attach
|
||||
- `agent rename` enforces unique active names; use `pane rename` only when duplicate labels are intentional
|
||||
- `agent start <name> -- <argv...>` starts a named pane-backed terminal and returns `result.agent` plus `result.argv`
|
||||
- `pane split` keeps focus where it is by default; pass `--focus` to switch to the new pane
|
||||
- `pane read` prints **text**, not json
|
||||
- `pane read --format ansi` and `pane read --ansi` print a rendered ANSI snapshot with colors/styles preserved
|
||||
|
|
|
|||
|
|
@ -108,6 +108,12 @@ Host workbox
|
|||
|
||||
same session, same agents, same state.
|
||||
|
||||
### direct agent attach
|
||||
|
||||
`herdr` and `herdr --remote` attach to the full Herdr session UI. `herdr agent attach <target>` attaches your current terminal directly to one server-owned terminal, like a single-pane terminal attach. `herdr terminal attach <terminal_id>` does the same by terminal id.
|
||||
|
||||
Direct attach streams the current rendered terminal state first, then live ANSI frames. Your input goes straight to that terminal. Detach with `ctrl+b q`; send a literal `ctrl+b` with `ctrl+b ctrl+b`. One writable client owns input and resize for a terminal. A second attach fails unless you pass `--takeover`.
|
||||
|
||||
## agent awareness
|
||||
|
||||
the sidebar shows which agents are blocked, working, or done. workspaces roll up to their most urgent state so you can scan the full list at a glance.
|
||||
|
|
@ -147,7 +153,7 @@ herdr tab create --label "logs"
|
|||
herdr pane split 1-1 --direction right
|
||||
herdr pane run 1-2 "npm test"
|
||||
|
||||
# wait for an agent
|
||||
# wait for a pane-level UI attention state
|
||||
herdr wait agent-status 1-1 --status done
|
||||
|
||||
# read output
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ if you are teaching an agent that is already running inside herdr, start with [`
|
|||
there are three practical ways to integrate with herdr:
|
||||
|
||||
- **agent skill** — [`SKILL.md`](./SKILL.md). best when an agent inside herdr just needs to learn the workflow quickly.
|
||||
- **cli wrappers** — `herdr server stop`, `herdr workspace ...`, `herdr tab ...`, `herdr pane ...`, `herdr wait ...`. best for shell scripts and simple orchestration.
|
||||
- **cli wrappers** — `herdr server stop`, `herdr workspace ...`, `herdr tab ...`, `herdr agent ...`, `herdr pane ...`, `herdr wait ...`. best for shell scripts and simple orchestration.
|
||||
- **raw socket api** — best when you want direct request/response control or long-lived event subscriptions.
|
||||
|
||||
these layers are intentionally stacked on top of the same control surface.
|
||||
|
|
@ -141,6 +141,7 @@ for backward compatibility, requests also accept the older positional forms like
|
|||
```json
|
||||
{
|
||||
"pane_id": "w64e95948145ed1-1",
|
||||
"terminal_id": "term_64e95948145ed1",
|
||||
"workspace_id": "w64e95948145ed1",
|
||||
"tab_id": "w64e95948145ed1:1",
|
||||
"focused": true,
|
||||
|
|
@ -153,8 +154,30 @@ for backward compatibility, requests also accept the older positional forms like
|
|||
}
|
||||
```
|
||||
|
||||
`terminal_id` is an opaque terminal identity. during the pane-backed transition each pane has one terminal id, but clients should not derive it from the pane id.
|
||||
|
||||
`label` is an optional manual pane name set through `pane.rename`.
|
||||
|
||||
`agent_info` responses contain a terminal-facing view of a live agent terminal:
|
||||
|
||||
```json
|
||||
{
|
||||
"terminal_id": "term_64e95948145ed1",
|
||||
"name": "reviewer",
|
||||
"agent": "pi",
|
||||
"agent_status": "working",
|
||||
"custom_status": "indexing",
|
||||
"workspace_id": "w64e95948145ed1",
|
||||
"tab_id": "w64e95948145ed1:1",
|
||||
"pane_id": "w64e95948145ed1-1",
|
||||
"focused": true,
|
||||
"cwd": "/home/can/Projects/herdr",
|
||||
"revision": 0
|
||||
}
|
||||
```
|
||||
|
||||
`name` is an optional unique agent alias set by `agent.start` or `agent.rename`. it is separate from the pane `label`: `pane.rename` names a terminal/pane for UI purposes, while `agent.rename` declares or changes the agent-facing name and rejects duplicate active agent names.
|
||||
|
||||
`agent` is an optional display label string.
|
||||
|
||||
- when herdr detects a built-in agent, this is that built-in name like `pi` or `claude`
|
||||
|
|
@ -206,6 +229,13 @@ for backward compatibility, requests also accept the older positional forms like
|
|||
| `tab.focus` | focus a tab | `tab_info` |
|
||||
| `tab.rename` | rename a tab | `tab_info` |
|
||||
| `tab.close` | close a tab | `ok` |
|
||||
| `agent.list` | list terminal-backed agents | `agent_list` |
|
||||
| `agent.get` | inspect one agent by terminal id, unique agent name, detected agent label, or pane id | `agent_info` |
|
||||
| `agent.read` | read output from one agent terminal | `pane_read` |
|
||||
| `agent.send` | send literal text to one agent terminal | `ok` |
|
||||
| `agent.rename` | set or clear the unique agent name | `agent_info` |
|
||||
| `agent.focus` | show the agent terminal in the TUI | `agent_info` |
|
||||
| `agent.start` | start a named agent terminal from argv | `agent_started` |
|
||||
| `pane.list` | list panes, optionally filtered by workspace | `pane_list` |
|
||||
| `pane.get` | inspect one pane | `pane_info` |
|
||||
| `pane.rename` | set or clear a manual pane label | `pane_info` |
|
||||
|
|
@ -968,6 +998,30 @@ herdr tab rename <tab_id> <label>
|
|||
herdr tab close <tab_id>
|
||||
```
|
||||
|
||||
agent commands:
|
||||
|
||||
```text
|
||||
herdr agent list
|
||||
herdr agent get <target>
|
||||
herdr agent read <target> [--source visible|recent|recent-unwrapped] [--lines N] [--format text|ansi] [--ansi]
|
||||
herdr agent send <target> <text>
|
||||
herdr agent rename <target> <name>|--clear
|
||||
herdr agent focus <target>
|
||||
herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
|
||||
herdr agent attach <target> [--takeover]
|
||||
herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--focus|--no-focus] -- <argv...>
|
||||
```
|
||||
|
||||
agent targets accept terminal ids, unique agent names, detected/reported agent labels, and legacy pane ids. `agent list` shows terminals with explicit agent identity, detected/reported agent identity, or `agent.start` launch metadata. `pane.rename` does not make a plain terminal appear in `agent list`; use `agent.rename` for agent identity.
|
||||
|
||||
terminal commands:
|
||||
|
||||
```text
|
||||
herdr terminal attach <terminal_id> [--takeover]
|
||||
```
|
||||
|
||||
`terminal attach` is the low-level direct attach primitive. it streams the current rendered terminal state first, then live ANSI frames. direct attach has one writable input/resize owner; a second direct attach fails unless you pass `--takeover`. detach with `ctrl+b q`; send a literal `ctrl+b` with `ctrl+b ctrl+b`.
|
||||
|
||||
pane commands:
|
||||
|
||||
```text
|
||||
|
|
@ -1003,6 +1057,11 @@ herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [
|
|||
- `tab create` without `--label` keeps the default numbered tab naming
|
||||
- `tab create --label` applies the custom tab name immediately
|
||||
- `tab create` returns `result.tab` and `result.root_pane`
|
||||
- `agent list` shows agent terminals, not arbitrary named panes
|
||||
- `agent wait --status idle` is the CLI completion wait; it treats the UI-only `done` attention state as satisfying idle
|
||||
- `agent focus` switches the TUI workspace/tab/pane focus; it is not direct terminal attach
|
||||
- `agent attach` attaches the current terminal directly to the agent terminal stream
|
||||
- `agent start <name> -- <argv...>` starts a named agent terminal and returns `result.agent` plus `result.argv`
|
||||
- `pane split` keeps focus where it is by default; pass `--focus` to switch to the new pane
|
||||
- `pane read` prints **text**, not json
|
||||
- `pane read --format ansi` and `pane read --ansi` print a rendered ANSI snapshot with colors/styles preserved
|
||||
|
|
@ -1026,7 +1085,13 @@ herdr pane run 1-2 "npm run dev"
|
|||
herdr wait output 1-2 --match "ready" --timeout 30000
|
||||
```
|
||||
|
||||
wait for another agent to finish in the same user-facing sense the UI shows:
|
||||
wait for an agent by name to become idle for CLI automation:
|
||||
|
||||
```bash
|
||||
herdr agent wait reviewer --status idle --timeout 60000
|
||||
```
|
||||
|
||||
wait for a pane-level UI attention state:
|
||||
|
||||
```bash
|
||||
herdr wait agent-status 1-1 --status done --timeout 60000
|
||||
|
|
|
|||
Loading…
Reference in New Issue