herdr
Skill428 starsChanged 4 months agoMITView on GitHub
Control Herdr, a terminl multiplexer for coding agents. Use Herdr to inspect or control panes, tabs, workspaces, terminals, run commands, and or starting and monitoring background processes like dev servers. Use for subagent when the user or another skills explicitly asks for or requies subagents. Requires HERDR_ENV=1.
51 other projects use a version of this, 32 of them edited.
Adopted by
Most recently taken up by
- luther-io/skillstheir own version, first seen Nov 16, 2026
- davidondrej/skillstheir own version, first seen Nov 15, 2026
- compozy/compozyedited, first seen Nov 13, 2026
- cypher0n3/dotagentsedited, first seen Nov 11, 2026
- juraj-blahunka/skillstheir own version, first seen Nov 8, 2026
- bepaldes/heimdall-agentedited, first seen Nov 8, 2026
Used with
Projects with it also use better-accessibility, show-me and 9 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
AnasX7Skillbetter-accessibility
Helps your project comply with accessibility standards and best practices.
Also in 3 projects that use this
AnasX7Skillshow-me
Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
Also in 5 projects that use this
kannaka-labsSkillskill-doctor
Environment diagnostics — check providers, auth, config, hooks, scheduler, and more. Use when: AUTOMATICALLY ACTIVATE when user asks about:. \"doctor\" or \"run doctor\" or \"diagnostics\". \"check my setup\" or \"is everything working\"
Also in 3 projects that use this
GoogleSkillwayfinder
Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
Also in 6 projects that use this
AWSSkillwizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
Also in 5 projects that use this
MicrosoftSkillwriting-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
Also in 7 projects that use this
Other versions51 projects use a version of this.
Word for word · 0
None found.
Edited · 32
- ogulcancelik/herdr★ 47k56% same
- herdrdev/herdr★ 47k56% same
- compozy/compozy★ 2.9k62% same
- sammcj/agentic-coding★ 16989% same
- romiluz13/mifal★ 4754% same
- hcchengithub/peforth★ 3744% same
- Mineru98/skills-store★ 1355% same
- Yassimba/loom★ 1331% same
- Spoon94/skill-vault★ 560% same
- ton-anywhere/my-favorite-prompts★ 560% same
22 more not listed
Wrote their own version · 19
- davidondrej/skills★ 4.3ksame name
- ninehills/skills★ 280same name
- ninehills/public-skills★ 86same name
- ulises-jeremias/agent-toolkit★ 20same name
- transparent-pegasus/herdr-orchestration★ 8same name
- yangyang0507/herdr-skill★ 3same name
- bmaltais/skills★ 2same name
- jbaham2/herdr-plugin★ 1same name
- luther-io/skills★ 1same name
- MarioJames/skill-foundry★ 1same name
9 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- broSkill
- cloudflare-composition-rootSkill
- coding-standardsSkill
- effect-service-designSkill
- preludeSkill
- tech-specSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. 0 are common, 9 are distinctive, and 11 are very specific to this project.
0
Common
Most of the 50 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Before issuing any control command, verify that this agent is running inside a Herdr-managed pane:
- Distinctive: line 16
If the check fails, say that you are not running inside Herdr and stop.
- Very specific: line 18
When the check passes, the herdr binary in PATH talks to the current session.
- Very specific: line 42
Do not run bare herdr for discovery.
- Very specific: line 76
Prefer --current when a pane command should target the calling pane.
- Distinctive: line 92
Default to a sibling pane in the current tab and the current working directory.
- Very specific: line 114
Use the kind requested by the user.
- Very specific: line 132
Use --until only for a state-specific workflow, such as waiting for an already-running agent to request input:
- Distinctive: line 140
Use logical keys for interactive agent UI controls:
- Very specific: line 154
If a wait fails or returns blocked, inspect agent get and agent read before deciding what input to send.
- Distinctive: line 158
Create a sibling pane with the same geometry rule, preserve the caller's working directory, and keep user focus unchanged:
- Very specific: line 164
Read the new pane ID from .result.pane.pane_id, then run and inspect the command:
- Distinctive: line 174
Use the read source that matches the task:
- Very specific: line 181
Use --format ansi when colors and terminal styling are evidence.
- Distinctive: line 185
After that failed read, ask the agent to write its complete response as Markdown in a temporary directory and reply only with the file …
- Very specific: line 189
Use --no-focus for background work unless the user asked to switch context.
- Very specific: line 190
Use --current, an explicit pane ID, or a unique agent name.
- Distinctive: line 192
Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked.
- Very specific: line 193
Never run herdr server stop from an active session unless the user explicitly intends to stop the server and its pane processes.
- Distinctive: line 194
Never kill the main Herdr process.
“Common” is measured: kept by at least 6 in 10 of the 50 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Herdr
Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding agents running inside panes, and exposes the current session through the herdr CLI.
Before issuing any control command, verify that this agent is running inside a Herdr-managed pane:
test "${HERDR_ENV:-}" = 1If 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.
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.
Learn the current CLI
The installed binary is the authority for command syntax. Start with:
herdr --helpThen print the relevant command group by running the group without a subcommand:
herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr sessionDo 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.
Most control commands return JSON. Read identifiers and state from those responses instead of predicting them.
Understand layout, panes, and agents
Choose the primitive that matches the job:
- Workspace, tab, and pane topology organize terminal locations.
- Pane commands control raw terminals, shells, tests, servers, input, and output.
- Agent commands control the recognized coding agent currently occupying a pane.
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.
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.
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.
Use IDs and caller context
Public IDs are opaque stable handles:
- workspace:
w1 - tab:
w1:t1 - pane:
w1:p1
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.
Herdr injects the caller's context into each managed pane:
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"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.
Discover live state with:
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent listCreation 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.
Start and coordinate an agent
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.
Honor a direction requested by the user. Otherwise inspect the caller pane:
herdr pane layout --pane "$HERDR_PANE_ID"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:
herdr pane split --current --direction right --cwd "$PWD" --no-focusReplace right with down when appropriate. Read the new pane ID from .result.pane.pane_id.
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:
herdr agent start reviewer --kind codex --pane <returned-pane-id>Use the kind requested by the user. Run herdr agent to inspect the installed kind list and options. Pass native agent arguments only after --:
herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>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.
Submit work through the agent surface:
herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000agent 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.
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.
Use --until only for a state-specific workflow, such as waiting for an already-running agent to request input:
herdr agent wait reviewer --until blocked --timeout 120000Without --until, standalone agent wait uses the same settled-state defaults as agent prompt --wait.
Use logical keys for interactive agent UI controls:
herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+cHerdr validates all keys before writing any bytes. Read the result through the resolved agent:
herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120If 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.
Run an ordinary command in another pane
Create a sibling pane with the same geometry rule, preserve the caller's working directory, and keep user focus unchanged:
herdr pane split --current --direction right --cwd "$PWD" --no-focusRead the new pane ID from .result.pane.pane_id, then run and inspect the command:
herdr pane run <returned-pane-id> "just test"
herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120pane 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.
Use the read source that matches the task:
visible: the currently rendered viewport.recent: recent rendered output, including soft wraps.recent-unwrapped: recent output with soft wraps joined; prefer it for logs and transcripts.detection: the plain-text bottom-buffer snapshot used for agent detection.
Use --format ansi when colors and terminal styling are evidence. Otherwise use text.
--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.
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.
Safety and coordination rules
- Use
--no-focusfor background work unless the user asked to switch context. - Use
--current, an explicit pane ID, or a unique agent name. Do not rely on another client's focused pane. - Parse IDs from JSON responses. Do not derive them from sidebar order or examples.
- Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked.
- Never run
herdr server stopfrom an active session unless the user explicitly intends to stop the server and its pane processes. - Never kill the main Herdr process. Use named test sessions for experiments that need an isolated server.
- CLI server errors are JSON on stderr with exit status 1. CLI syntax errors exit with status 2.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

