# Herdr

> Manage Herdr workspaces, tabs, and panes for Agent Toolkit swarms with eager windows, shell-aware

- **Type:** Skill
- **Install:** `agentstack add skill-ulises-jeremias-agent-toolkit-herdr`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ulises-jeremias](https://agentstack.voostack.com/s/ulises-jeremias)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ulises-jeremias](https://github.com/ulises-jeremias)
- **Source:** https://github.com/ulises-jeremias/agent-toolkit/tree/main/plugins/agent-toolkit-complete/.github/skills/herdr
- **Website:** https://ulises-jeremias.github.io/agent-toolkit-archive/

## Install

```sh
agentstack add skill-ulises-jeremias-agent-toolkit-herdr
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Herdr

Operate Herdr as the primary UI for `agent-toolkit swarm` — eager tabs, shell-consistent execution (`zsh`/`bash` via `_user_shell()`), and clean reuse of windows. This skill is the Herdr complement to `swarm` and `swarm-observer`.

## When to use

- Swarm was started with `--ui herdr` (default) and you need to inspect or recover Herdr state.
- `herdr workspace list/create/tab create/pane run` behavior is unexpected (extra workspaces `w7-wA` for `headless`, wrong `--cwd`, or missing eager windows).
- User prefers Herdr over tmux for its excellent interactive UX and wants to reuse tabs for sequential requests.

## Prerequisites

- `herdr` CLI installed and daemon running (`herdr --version`, `herdr workspace list --json` works; `--json` may be unsupported on older binaries — fallback to text).
- Swarm run exists: `.agent-toolkit/swarm/runs//state.json` with `ui: herdr`.
- Repo is a Git directory (worktrees are created under `.agent-toolkit/swarm/runs//worktrees/`).

## Workflow

### 1. Verify backend and shell

```bash
agent-toolkit swarm doctor --json | jq '.backends'
herdr --version
echo $SHELL; getent passwd $USER | cut -d: -f7  # should be /usr/bin/zsh on this host
# swarm's _user_shell() picks: $SHELL -> pwd.getpwuid -> /usr/bin/zsh -> /bin/bash
```

### 2. Inspect Herdr state for a run

```bash
herdr workspace list --json 2>&1 | jq '.[] | {id,name,path,status}' | head -n 40
# Expected: one workspace per run: swarm-20260807T...-
# Orphan check: workspaces w7-wA with headless run-id -> delete after fixing backend

agent-toolkit swarm status --run-id  --json | jq '{ui,recipe,runner,model_profile,worktrees,handoffs}'
agent-toolkit swarm handoffs --run-id  --json | jq
herdr workspace list | grep swarm-
```

### 3. Eager windows (automatic on swarm start)

On `swarm start --ui herdr`, swarm creates **one tab per role** immediately:

- `tab create --workspace swarm- --name ` for each role (`implementer`, `reviewer`, `integrator`, ... plus `1` for coordinator).
- Each non-implementer tab runs: `echo "Waiting for handoff:  ->  | role:  | run: "` via ` -lc` (quoted to avoid `| pipe` issues) and records `agent_waiting` trace.
- `select-window` / `workspace focus` focuses `implementer`; implementer pane runs `export AGENT_TOOLKIT_SWARM_RUN_ID=... RUN_DIR=... REPO=... SWARMFORGE_ROLE=implementer && cd  && exec  "$(cat prompt)"`.

If a tab is missing:

```bash
herdr tab create --workspace swarm- --name reviewer --json 2>&1 | jq
herdr pane run --workspace swarm- --tab reviewer --command "/usr/bin/zsh -lc 'echo \"Waiting for handoff: implementer -> reviewer | role: reviewer | run: \"'" --json 2>&1 | jq
```

### 4. Recover from known pitfalls

| Symptom | Fix |
|---------|-----|
| Extra workspaces for `headless` runs | `get_backend("headless")` fallback created spurious Herdr workspaces. Patch `swarm/backends/__init__.py` to return headless/noop backend; then `herdr workspace delete ` for orphans. |
| `--cwd` wrong (repo not found) | Ensure `herdr workspace create --cwd ` uses `find_repo_root` result, not `cwd` when run from worktree. |
| `pane run` fails with `pipe` | Swarm fixed by quoting waiting message: `echo "Waiting..."` not `echo Waiting ... |` |
| Shell mismatch (`bash` vs `zsh`) | Swarm now uses `_user_shell()`; verify Herdr panes inherit `$SHELL`. `herdr pane run --command "/usr/bin/zsh -lc 'echo \$SHELL'"` |

### 5. Reuse tabs for new requests

Do not delete the workspace between tasks. Reuse the same `run-id`:

```bash
agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/next-task.md --run-id 
# Herdr tabs stay; only the handoff chain retriggers. New run only for isolated branch.
```

Attach when needed:

```bash
agent-toolkit swarm attach --run-id 
herdr workspace focus --workspace swarm-
```

## Boundaries

- Never write Herdr's workspace DB directly; use `herdr workspace/tab/pane` CLI via swarm's `HerdrBackend`.
- Never mix Herdr and tmux sockets — swarm uses `herdr` OR isolated `tmux -L agent-toolkit-swarm-`, never both for one run.
- Do not run `herdr workspace open` (removed); use `workspace focus` / `workspace list`.

## Delegates to

| Need | Skill |
|------|-------|
| Launch or reuse a swarm | `swarm` |
| Diagnose stuck handoffs/logs | `swarm-observer` |
| Create file handoffs | `swarm-handoff` |
| Isolated fallback when Herdr unavailable | `tmux` (via `swarm --ui tmux`) |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ulises-jeremias](https://github.com/ulises-jeremias)
- **Source:** [ulises-jeremias/agent-toolkit](https://github.com/ulises-jeremias/agent-toolkit)
- **License:** MIT
- **Homepage:** https://ulises-jeremias.github.io/agent-toolkit-archive/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ulises-jeremias-agent-toolkit-herdr
- Seller: https://agentstack.voostack.com/s/ulises-jeremias
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.