herdr

Category: Tools & Productivity | Uploader: ogulcancelik | Downloads: 0 | Version: v1.0（Latest）

Control herdr from inside it. Split panes, spawn agents, read output, wait for state changes, and manage workspaces — all via CLI commands that talk to the running herdr instance over a local unix socket. Use when running inside herdr (HERDR_ENV=1).

Changelog: Source: GitHub https://github.com/ogulcancelik/herdr

Directory Structure

Current level: tree/master/

📁 .github/
- 📁 workflows/
  - 📄 release.yml 2.8 KB
📁 .pi/
- 📁 prompts/
  - 📄 draft-changelog.md 2.7 KB
📁 assets/
- 📁 sounds/
  - 📄 done.mp3 33.8 KB
  - 📄 request.mp3 45.7 KB
- 📄 logo.png 117.8 KB
- 📄 og-card.png 362.8 KB
- 📄 screenshot.png 597.3 KB
📁 scripts/
- 📄 __init__.py 0 B
- 📄 capture_key_matrix.py 7.6 KB
- 📄 capture_keys.py 2.3 KB
- 📄 changelog.py 4.7 KB
- 📄 test_changelog.py 1.5 KB
- 📄 verify_suspicious_keys.py 6.3 KB
📁 src/
- 📁 api/
  - 📄 mod.rs 25.2 KB
  - 📄 schema.rs 19.0 KB
- 📁 app/
  - 📄 actions.rs 18.5 KB
  - 📄 input.rs 58.8 KB
  - 📄 mod.rs 49.1 KB
  - 📄 state.rs 21.2 KB
- 📁 input/
  - 📄 encode.rs 10.5 KB
  - 📄 mod.rs 203 B
  - 📄 model.rs 1.5 KB
  - 📄 parse.rs 11.4 KB
  - 📄 tests.rs 19.8 KB
- 📁 platform/
  - 📄 fallback.rs 254 B
  - 📄 linux.rs 2.7 KB
  - 📄 macos.rs 7.4 KB
  - 📄 mod.rs 844 B
- 📄 cli.rs 22.2 KB
- 📄 config.rs 31.2 KB
- 📄 detect.rs 36.7 KB
- 📄 events.rs 715 B
- 📄 layout.rs 14.6 KB
- 📄 main.rs 12.3 KB
- 📄 pane.rs 21.9 KB
- 📄 persist.rs 14.3 KB
- 📄 pty_callbacks.rs 12.8 KB
- 📄 raw_input.rs 21.2 KB
- 📄 selection.rs 8.1 KB
- 📄 sound.rs 1.9 KB
- 📄 ui.rs 57.8 KB
- 📄 update.rs 10.7 KB
- 📄 workspace.rs 16.4 KB
📁 tests/
- 📁 fixtures/
  - 📄 keyboard_protocol_corpus.tsv 947 B
  - 📄 linux_terminal_variants.tsv 1.1 KB
  - 📄 macos_terminal_variants.tsv 743 B
- 📁 integration/
  - 📁 ext/
    
    📄 herdr-test.ts 4.0 KB
  - 📁 results/
    
    📄 .gitignore 14 B
  - 📁 specs/
    
    📄 create_workspace.md 435 B
    
    📄 sidebar_collapse.md 605 B
    
    📄 split_and_navigate.md 499 B
    
    📄 workspace_switching.md 567 B
  - 📄 pdeathsig.py 1.3 KB
  - 📄 run_all.sh 3.1 KB
  - 📄 run_spec.sh 4.3 KB
  - 📄 system.md 1.8 KB
- 📄 api_ping.rs 18.2 KB
- 📄 cli_wrapper.rs 14.0 KB
📄 .gitignore 71 B
📄 AGENTS.md 2.1 KB
📄 Cargo.lock 50.5 KB
📄 Cargo.toml 883 B
📄 CHANGELOG.md 4.2 KB
📄 CONFIGURATION.md 5.7 KB
📄 justfile 1.8 KB
📄 LICENSE 33.7 KB
📄 README.md 12.3 KB
📄 SKILL.md 5.4 KB
📄 SOCKET_API.md 13.9 KB

SKILL.md

---
name: herdr
description: "Control herdr from inside it. Split panes, spawn agents, read output, wait for state changes, and manage workspaces — all via CLI commands that talk to the running herdr instance over a local unix socket. Use when running inside herdr (HERDR_ENV=1)."
---

# herdr — agent skill

you are running inside herdr, a terminal-native agent multiplexer. herdr gives you workspaces and panes — each pane is a real terminal with its own shell, agent, server, or log stream — and you can control all of it from the cli.

this means you can:

- see what other panes and agents are doing
- split panes and run commands in them
- start servers, watch logs, and run tests in sibling panes
- wait for specific output before continuing
- wait for another agent to finish
- spawn more agent instances

the `herdr` binary is available in your PATH. its workspace, pane, and wait commands talk to the running herdr instance over a local unix socket.

if you need the raw protocol or full api reference, read [`SOCKET_API.md`](./SOCKET_API.md).

## concepts

**workspaces** are project contexts. each workspace has one or more panes.

**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 and the state is calm
- `working` — agent is actively working
- `blocked` — agent needs input or approval
- `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 compact public ids for the current live session.

important: ids can compact when panes or workspaces are closed. do not treat them as durable ids.

## discover yourself

see what panes exist and which one is focused:

```bash
herdr pane list
```

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

list workspaces:

```bash
herdr workspace list
```

## read another pane

see what is on another pane's screen:

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

- `--source visible` = current viewport
- `--source recent` = recent scrollback

## split a pane and run a command

split your pane to the right and keep focus on your current pane:

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

that prints json with the new pane id. read the returned `pane_id`, then run a command in that pane:

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

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, and 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
```

if it times out, exit code is `1`.

## wait for an agent state

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 presses Enter:

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

## workspace management

create a new workspace:

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

create one without focusing it:

```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 wait until it is ready

```bash
# split a pane for the server
herdr pane split 1-2 --direction right --no-focus
# read the returned JSON to get the new pane_id, for example 1-3

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

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

# read the output to confirm
herdr pane read 1-3 --source recent --lines 20
```

### run tests in a separate pane and inspect the result

```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 1-3 --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"
herdr wait output 1-3 --match ">" --timeout 15000
herdr pane run 1-3 "review the test coverage in src/api/"
```

### coordinate with another agent

```bash
herdr wait agent-state 1-1 --state idle --timeout 120000
herdr pane read 1-1 --source recent --lines 100
```

## notes

- `workspace list`, `pane list`, `workspace create`, `pane split`, `wait output`, and `wait agent-state` print json on success.
- `pane read` prints text, not json.
- `pane send-text`, `pane send-keys`, and `pane run` print nothing on success.
- parse ids from `workspace create` and `pane split` responses when you need the new ids. do not guess.
- `--no-focus` on split and workspace create keeps your current terminal context focused.
- if you are running inside herdr, the `HERDR_ENV` environment variable is set to `1`.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

herdr

Directory Structure

SKILL.md

Report

Notice