herdr

Name: herdr
Author: ogulcancelik

byogulcancelik· 5 skills

Installs

15k

Stars

22k

Forks

1.5k

How to install herdr?

ogulcancelik/herdr

$npx -y skills add ogulcancelik/herdr --skill herdr

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/ogulcancelik/herdr" --skill "ogulcancelik/herdr"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/ogulcancelik/herdr" that are relevant to the current task. Run `npx skills add "https://github.com/ogulcancelik/herdr"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Herdr
2
3	Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding agents running inside panes, and exposes the current session through the `herdr` CLI.
4
5	Before issuing any control command, verify that this agent is running inside a Herdr-managed pane:
6
7	```bash
8	test "${HERDR_ENV:-}" = 1
9	```
10
11	If the check fails, say that you are not running inside Herdr and stop. Do not inspect or control the focused Herdr session from outside Herdr.
12
13	When the check passes, the `herdr` binary in `PATH` talks to the current session. Use it to inspect neighboring work, create terminal layout, start agents and commands, read output, and wait for state changes.
14
15	## Learn the current CLI
16
17	The installed binary is the authority for command syntax. Start with:
18
19	```bash
20	herdr --help
21	```
22
23	Then print the relevant command group by running the group without a subcommand:
24
25	```bash
26	herdr agent
27	herdr pane
28	herdr workspace
29	herdr tab
30	herdr worktree
31	herdr terminal
32	herdr notification
33	herdr integration
34	herdr session
35	```
36
37	Do not run bare `herdr` for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments. Commands such as `herdr workspace create` are valid with defaults and will execute.
38
39	Most control commands return JSON. Read identifiers and state from those responses instead of predicting them.
40
41	## Understand layout, panes, and agents
42
43	Choose the primitive that matches the job:
44
45	- Workspace, tab, and pane topology organize terminal locations.
46	- Pane commands control raw terminals, shells, tests, servers, input, and output.
47	- Agent commands control the recognized coding agent currently occupying a pane.
48
49	A pane exists whether or not it contains an agent. `agent start` requires an existing available shell pane and never creates, splits, or moves layout. Use pane commands for ordinary processes. Use agent commands when Herdr must validate agent identity or interpret `idle`, `working`, `blocked`, `done`, and `unknown` lifecycle states.
50
51	Agent commands accept either a unique live agent name or the pane ID currently hosting that agent. They do not accept terminal IDs or bare agent-kind labels. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced.
52
53	`idle` means the agent is ready for input and its tab has been seen in the focused Herdr UI. `done` is the same underlying idle state after unseen background work finishes. Focusing the tab or targeting the pane or agent with a focus command marks it seen. CLI reads do not mark it seen. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently; it does not prove completion.
54
55	## Use IDs and caller context
56
57	Public IDs are opaque stable handles:
58
59	- workspace: `w1`
60	- tab: `w1:t1`
61	- pane: `w1:p1`
62
63	Closed tab and pane IDs are not reused. A pane moved into another workspace receives a new workspace-qualified pane ID. After `pane move`, continue with `.result.move_result.pane.pane_id` or the live agent name. The old value is reported as `.result.move_result.previous_pane_id`; only the moved process's inherited caller context keeps resolving that old ID, so do not use it as a general agent target.
64
65	Herdr injects the caller's context into each managed pane:
66
67	```bash
68	printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"
69	```
70
71	Prefer `--current` when a pane command should target the calling pane. Omitting a target may use the UI-focused pane, which can belong to the user or another client.
72
73	Discover live state with:
74
75	```bash
76	herdr workspace list
77	herdr tab list --workspace "$HERDR_WORKSPACE_ID"
78	herdr pane current --current
79	herdr pane list --workspace "$HERDR_WORKSPACE_ID"
80	herdr agent list
81	```
82
83	Creation responses expose the IDs to use next. `workspace create` returns `.result.workspace`, `.result.tab`, and `.result.root_pane`. `tab create` returns `.result.tab` and `.result.root_pane`. `pane split` returns the new pane as `.result.pane`.
84
85	## Start and coordinate an agent
86
87	Default to a sibling pane in the current tab and the current working directory. Do not create a workspace, tab, worktree, or different cwd unless the user explicitly requests that topology or location.
88
89	Honor a direction requested by the user. Otherwise inspect the caller pane:
90
91	```bash
92	herdr pane layout --pane "$HERDR_PANE_ID"
93	```
94
95	Split a wide pane to the right and a narrow or tall pane down. Avoid repeated same-direction splits that create unusably narrow columns or short rows. Keep the user's focus in the calling pane and explicitly preserve the caller's working directory:
96
97	```bash
98	herdr pane split --current --direction right --cwd "$PWD" --no-focus
99	```
100
101	Replace `right` with `down` when appropriate. Read the new pane ID from `.result.pane.pane_id`.
102
103	An available shell pane must be at its interactive prompt, with the shell itself in the foreground and no foreground command, editor, or agent running. Start a supported agent in that pane with a useful unique name:
104
105	```bash
106	herdr agent start reviewer --kind codex --pane <returned-pane-id>
107	```
108
109	Use the kind requested by the user. Run `herdr agent` to inspect the installed kind list and options. Pass native agent arguments only after `--`:
110
111	```bash
112	herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>
113	```
114
115	`agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. It defaults to a 30-second startup timeout.
116
117	Submit work through the agent surface:
118
119	```bash
120	herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
121	```
122
123	`agent prompt` atomically submits text and encoded Enter while honoring the pane's live bracketed-paste mode. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`.
124
125	A prompt sent from a non-working state must produce an observed lifecycle change within five seconds. Otherwise Herdr returns `agent_prompt_stalled` instead of waiting indefinitely. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it.
126
127	Use `--until` only for a state-specific workflow, such as waiting for an already-running agent to request input:
128
129	```bash
130	herdr agent wait reviewer --until blocked --timeout 120000
131	```
132
133	Without `--until`, standalone `agent wait` uses the same settled-state defaults as `agent prompt --wait`.
134
135	Use logical keys for interactive agent UI controls:
136
137	```bash
138	herdr agent send-keys reviewer esc
139	herdr agent send-keys reviewer ctrl+c
140	```
141
142	Herdr validates all keys before writing any bytes. Read the result through the resolved agent:
143
144	```bash
145	herdr agent get reviewer
146	herdr agent read reviewer --source recent-unwrapped --lines 120
147	```
148
149	If a wait fails or returns `blocked`, inspect `agent get` and `agent read` before deciding what input to send. Use the pane surface only when raw terminal control is intentional.
150
151	## Run an ordinary command in another pane
152
153	Create a sibling pane with the same geometry rule, preserve the caller's working directory, and keep user focus unchanged:
154
155	```bash
156	herdr pane split --current --direction right --cwd "$PWD" --no-focus
157	```
158
159	Read the new pane ID from `.result.pane.pane_id`, then run and inspect the command:
160
161	```bash
162	herdr pane run <returned-pane-id> "just test"
163	herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
164	herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
165	```
166
167	`pane run` atomically sends command text and Enter. `pane wait-output` searches the selected snapshot immediately, so output that already exists can match. Use `--match <text>` for a literal substring or `--regex <pattern>` for a Rust regular expression. Omitting `--timeout` allows an indefinite wait.
168
169	Use the read source that matches the task:
170
171	- `visible`: the currently rendered viewport.
172	- `recent`: recent rendered output, including soft wraps.
173	- `recent-unwrapped`: recent output with soft wraps joined; prefer it for logs and transcripts.
174	- `detection`: the plain-text bottom-buffer snapshot used for agent detection.
175
176	Use `--format ansi` when colors and terminal styling are evidence. Otherwise use text.
177
178	`--lines` asks Herdr for more rows from the pane's available screen and host scrollback. If increasing it does not reveal more of a completed response, the pane is probably running the agent on the terminal's alternate screen. Rows that leave the alternate screen do not enter Herdr's host scrollback, so a larger line count cannot recover them.
179
180	After that failed read, ask the agent to write its complete response as Markdown in a temporary directory and reply only with the file path, then read the file directly. Use this only as a fallback; do not request file output in the initial prompt.
181
182	## Safety and coordination rules
183
184	- Use `--no-focus` for background work unless the user asked to switch context.
185	- Use `--current`, an explicit pane ID, or a unique agent name. Do not rely on another client's focused pane.
186	- Parse IDs from JSON responses. Do not derive them from sidebar order or examples.
187	- Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked.
188	- Never run `herdr server stop` from an active session unless the user explicitly intends to stop the server and its pane processes.
189	- Never kill the main Herdr process. Use named test sessions for experiments that need an isolated server.
190	- CLI server errors are JSON on stderr with exit status 1. CLI syntax errors exit with status 2.

6 picks

Type

Run `npx skills use "https://github.com/ogulcancelik/herdr" --skill "ogulcancelik/herdr"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/ogulcancelik/herdr" that are relevant to the current task. Run `npx skills add "https://github.com/ogulcancelik/herdr"` and select the relevant skills, then follow their instructions.

herdr

How to install herdr?

Related

herdr

How to install herdr?

Related