aboutsummaryrefslogtreecommitdiff
path: root/SKILL.md
blob: c0ba3061213e7b189fcbd35780546810e60df617 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
# herdr — agent skill

you are running inside herdr, a terminal workspace manager. herdr gives you workspaces (tabs) and panes (splits) — each pane is a full terminal with its own shell or agent. you can control all of it from the CLI.

this means you can:
- see what other agents/panes are doing
- split panes and run commands in them
- start servers, watch logs, run tests — in separate panes
- wait for specific output before continuing
- wait for another agent to finish
- spawn new agent instances

the `herdr` binary is available in your PATH. all commands talk to the running herdr instance over a local unix socket.

## concepts

**workspaces** are like tabs. each workspace has one or more panes. you switch between workspaces in the sidebar.

**panes** are terminal splits inside a workspace. each pane runs its own process — a shell, an agent, a server, anything.

**agent state** is detected automatically by herdr. each pane can be:
- `idle` — agent finished, user has seen it
- `busy` — agent is working
- `waiting` — agent needs user input
- `unknown` — no recognized agent, or just a shell

**ids** — workspace ids look like `1`, `2`. pane ids look like `1-1`, `1-2`, `2-1`. these are the public ids you should use.

## discover yourself

find out which pane you're in and what else is running:

```bash
herdr pane list
```

```json
{"id":"cli:pane:list","result":{"panes":[
  {"agent":"claude","agent_state":"waiting","cwd":"/home/user/project","focused":true,"pane_id":"1-2","workspace_id":"1"},
  {"agent":"pi","agent_state":"idle","cwd":"/home/user/project","focused":false,"pane_id":"1-1","workspace_id":"1"}
],"type":"pane_list"}}
```

the focused pane is yours. other panes are your neighbors.

```bash
herdr workspace list
```

```json
{"id":"cli:workspace:list","result":{"type":"workspace_list","workspaces":[
  {"workspace_id":"1","number":1,"label":"project","focused":true,"pane_count":2,"agent_state":"waiting"}
]}}
```

## read another pane

see what's on another pane's screen:

```bash
herdr pane read 1-1 --source recent --lines 50
```

`--source visible` shows the current viewport. `--source recent` shows recent scrollback (default).

## split a pane and run a command

split your pane to the right and run a dev server:

```bash
herdr pane split 1-2 --direction right --no-focus
```

this returns the new pane's id. then run a command in it:

```bash
herdr pane run 1-3 "npm run dev"
```

`pane run` sends the text and presses Enter. use `--no-focus` on split to keep focus on your pane.

split downward instead:

```bash
herdr pane split 1-2 --direction down --no-focus
```

## wait for output

block until specific text appears in a pane. useful for waiting on servers, builds, tests:

```bash
herdr wait output 1-3 --match "ready on port 3000" --timeout 30000
```

with regex:

```bash
herdr wait output 1-3 --match "server.*ready" --regex --timeout 30000
```

timeout is in milliseconds. if it times out, exit code is 1.

## wait for an agent to finish

block until another agent reaches a specific state:

```bash
herdr wait agent-state 1-1 --state idle --timeout 60000
```

useful when you need another agent to finish before you proceed.

## send text or keys to a pane

send text without pressing Enter:

```bash
herdr pane send-text 1-1 "hello from claude"
```

press Enter (or other keys):

```bash
herdr pane send-keys 1-1 Enter
```

`pane run` combines both — sends text then Enter:

```bash
herdr pane run 1-1 "echo hello"
```

## workspace management

create a new workspace:

```bash
herdr workspace create --cwd /path/to/project
```

```bash
herdr workspace create --no-focus
```

focus a workspace:

```bash
herdr workspace focus 2
```

rename:

```bash
herdr workspace rename 1 "api server"
```

close:

```bash
herdr workspace close 2
```

## close a pane

```bash
herdr pane close 1-3
```

## recipes

### run a server and watch for ready

```bash
# split a pane for the server
herdr pane split 1-2 --direction right --no-focus
# assume new pane is 1-3 from the response

# start the server
herdr pane run 1-3 "npm run dev"

# wait until it's ready
herdr wait output 1-3 --match "ready" --timeout 30000

# now read the output to confirm
herdr pane read p_1_7 --source recent --lines 20
```

### run tests in a separate pane and check results

```bash
herdr pane split 1-2 --direction down --no-focus
herdr pane run 1-3 "cargo test"
herdr wait output 1-3 --match "test result" --timeout 60000
herdr pane read p_1_7 --source recent --lines 30
```

### check what another agent is working on

```bash
herdr pane list
herdr pane read 1-1 --source recent --lines 80
```

### spawn a new agent and give it a task

```bash
herdr pane split 1-2 --direction right --no-focus
herdr pane run 1-3 "claude"
# wait for it to start
herdr wait output 1-3 --match ">" --timeout 15000
# send it a task
herdr pane run 1-3 "review the test coverage in src/api/"
```

### coordinate with another agent

```bash
# wait for the other agent to finish its current work
herdr wait agent-state 1-1 --state idle --timeout 120000

# read what it produced
herdr pane read 1-1 --source recent --lines 100
```

## notes

- all commands return JSON. parse the response to get pane ids from splits, workspace ids from creates, etc.
- `pane run` = `pane send-text` + `pane send-keys Enter`. use the separate commands when you need finer control.
- pane ids from split responses are the source of truth — don't guess pane ids, read them from the response.
- `--no-focus` on split keeps your terminal focused. without it, herdr focuses the new pane.
- if you're running inside herdr, the `HERDR_ENV` environment variable is set to `1`. ids are compact and can change when panes/workspaces are closed.