agentleFS
yuanhaorannnnnnyuanhaorannnnnn/agent-skills/skills/herdr/SKILL.md

herdr

Skill0 starsChanged 59 days agoMITView on GitHub

Inspect or control Herdr. In a Herdr-managed pane (HERDR_ENV=1), use the local CLI; from ChatGPT Web, Mobile, or Desktop, use the herdr_control MCP Bridge and never fall back to the CLI.

50 other projects use a version of this, 6 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use better-accessibility, show-me and 10 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.
  • AnasX7Skill

    better-accessibility

    Helps your project comply with accessibility standards and best practices.

    Also in 3 projects that use this

  • AnasX7Skill

    show-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-labsSkill

    skill-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

  • GoogleSkill

    wayfinder

    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

  • AWSSkill

    wizard

    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

  • MicrosoftSkill

    writing-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

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 49 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    if HERDR_ENV=1, this is a Herdr-managed pane.

    line 16
  2. Distinctive:

    create tabs for separate subcontexts inside one workspace

    line 44
  3. Distinctive:

    start servers, watch logs, and run tests in sibling panes

    line 46
  4. Distinctive:

    wait for specific output before continuing

    line 47
  5. Distinctive:

    wait for another agent to finish

    line 48
  6. Very specific:

    use pane read for current output that already exists.

    line 325
  7. Very specific:

    if you are running inside herdr, the HERDR_ENV environment variable is set to 1.

    line 329

“Common” is measured: kept by at least 6 in 10 of the 49 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

herdr — agent skill

Minimal entry

First choose the runtime path below. For a basic status check, discover the workspace, tab, and pane IDs, then read the target pane. Read only the operation section needed for the user request; recipes and agent coordination are optional.

runtime routing

choose exactly one control path before doing anything:

  1. if HERDR_ENV=1, this is a Herdr-managed pane. use the herdr CLI instructions below.
  2. otherwise, if the mcp__herdr_control__* tools are available, this is an external ChatGPT client. use only the MCP Bridge instructions below.
  3. otherwise, report that the Herdr Bridge is unavailable and stop.

when HERDR_ENV is not 1, never inspect or control Herdr through the local herdr CLI, shell commands, socket files, or an HTTP fallback. ChatGPT Web, Mobile, and Desktop must always use the MCP Bridge.

external ChatGPT clients: MCP Bridge

use only the capabilities actually exposed in the current tool list:

  • mcp__herdr_control__list_agents — list current agents and status.
  • mcp__herdr_control__list_panes — list current panes and obtain fresh pane ids.
  • mcp__herdr_control__read_pane — read an existing pane.
  • mcp__herdr_control__prompt_agent — prompt an existing agent when the user authorized that write action.
  • mcp__herdr_control__pane_send_text, pane_send_keys, pane_run — type, key, or run a user-authorized command in an existing pane.
  • mcp__herdr_control__pane_wait_output, pane_split, pane_close — wait for output or manage a pane; closing requires explicit authorization for the exact pane.

pane ids are ephemeral. call list_agents or list_panes immediately before every pane operation; never reuse an id from an earlier turn. for writes, verify the selected pane still belongs to the intended target and report the resulting state.

if the requested operation is not exposed by the Bridge, say which capability is missing and stop. do not fall back to herdr CLI. in particular, do not imply that workspace, tab, split, run, close, or wait operations exist unless matching MCP tools are present.

Herdr-managed panes: local CLI

you are running inside herdr, a terminal-native agent multiplexer. herdr gives you workspaces, tabs, 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
  • create tabs for separate subcontexts inside one workspace
  • 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, tab, 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 the socket api docs.

concepts

workspaces are project contexts. each workspace has one or more tabs. unless manually renamed, a workspace's label follows the first tab's root pane — usually the repo name, otherwise the root pane's current folder name.

tabs are subcontexts inside a workspace. each tab has one or more panes.

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

agent status is detected automatically by herdr. the api exposes one public field for it:

  • agent_status — idle, working, blocked, done, unknown

done means the agent finished, but you have not looked at that finished pane yet.

plain shells still exist as panes, but herdr's sidebar agent section intentionally focuses on detected agents rather than listing every shell.

ids — workspace ids look like 1, 2. tab ids look like 1:1, 1:2, 2:1. 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 tabs, panes, or workspaces are closed. do not treat them as durable ids. re-read ids from workspace list, tab list, pane list, or create/split responses when you need a current id. do not guess that an older 1-3 is still the same pane later.

discover yourself

see what panes exist and which one is focused:

herdr pane list

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

list workspaces:

herdr workspace list

tab management

list tabs in the current workspace:

herdr tab list --workspace 1

create a new tab:

herdr tab create --workspace 1

without --label, the new tab keeps the default numbered tab name.

create and name it in one step:

herdr tab create --workspace 1 --label "logs"

rename it:

herdr tab rename 1:2 "logs"

focus it:

herdr tab focus 1:2

close it:

herdr tab close 1:2

read another pane

see what is on another pane's screen:

herdr pane read 1-1 --source recent --lines 50
  • --source visible = current viewport
  • --source recent = recent scrollback as rendered in the pane
  • --source recent-unwrapped = recent terminal text with soft wraps joined back together

split a pane and run a command

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

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

that prints json with the new pane nested at result.pane.pane_id. parse that value, then run a command in that pane:

NEW_PANE=$(herdr pane split 1-2 --direction right --no-focus | python3 -c 'import sys,json; print(json.load(sys.stdin)["result"]["pane"]["pane_id"])')
herdr pane run "$NEW_PANE" "npm run dev"

split downward instead:

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.

for --source recent, matching uses unwrapped recent terminal text, so pane width and soft wrapping do not break matches. pane read --source recent still shows the pane as rendered. if you want to inspect the same transcript that the waiter matches, use pane read --source recent-unwrapped.

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

with regex:

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

if it times out, exit code is 1.

wait for an agent status

block until another agent reaches a specific status:

herdr agent wait 1-1 --until done --timeout 60000

use this when you want the same done / idle distinction the UI shows.

send text or keys to a pane

send text without pressing Enter:

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

press Enter or other keys:

herdr pane send-keys 1-1 Enter

pane run sends the text and then a real Enter key in one request:

herdr pane run 1-1 "echo hello"

workspace management

create a new workspace:

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

without --label, the new workspace keeps the default cwd-based name.

create and name one in one step:

herdr workspace create --cwd /path/to/project --label "api server"

create one without focusing it:

herdr workspace create --no-focus

focus a workspace:

herdr workspace focus 2

rename:

herdr workspace rename 1 "api server"

close:

herdr workspace close 2

close a pane

herdr pane close 1-3

recipes

run a server and wait until it is ready

NEW_PANE=$(herdr pane split 1-2 --direction right --no-focus | python3 -c 'import sys,json; print(json.load(sys.stdin)["result"]["pane"]["pane_id"])')
herdr pane run "$NEW_PANE" "npm run dev"
herdr pane wait-output "$NEW_PANE" --match "ready" --timeout 30000
herdr pane read "$NEW_PANE" --source recent --lines 20

run tests in a separate pane and inspect the result

herdr pane split 1-2 --direction down --no-focus
herdr pane run 1-3 "cargo test"
herdr pane 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

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

watch another pane robustly

use this pattern when you need to coordinate with a sibling pane:

# inspect what is already there
herdr pane read 1-3 --source recent --lines 40

# wait only for the next output you expect
herdr pane wait-output 1-3 --match "ready" --timeout 30000

# if you need to inspect the same transcript the waiter matched,
# read the unwrapped recent text directly
herdr pane read 1-3 --source recent-unwrapped --lines 40

spawn a new agent and give it a task

herdr pane split 1-2 --direction right --no-focus
herdr pane run 1-3 "claude"
herdr pane wait-output 1-3 --match ">" --timeout 15000
herdr pane run 1-3 "review the test coverage in src/api/"

coordinate with another agent

herdr agent wait 1-1 --until done --timeout 120000
herdr pane read 1-1 --source recent --lines 100

notes

  • workspace list, workspace create, tab list, tab create, tab get, tab focus, tab rename, tab close, pane list, pane get, pane split, pane wait-output, and agent wait print json on success.
  • pane read prints text, not json.
  • pane read --format ansi or pane read --ansi returns a rendered ANSI snapshot for TUI feedback loops.
  • pane read --source recent-unwrapped is useful when you want to inspect the same unwrapped transcript that pane wait-output --source recent matches against.
  • pane send-text, pane send-keys, and pane run print nothing on success.
  • parse ids from workspace create, tab create, and pane split responses when you need new ids. workspace create returns result.workspace, result.tab, and result.root_pane. tab create returns result.tab and result.root_pane. for pane split, the new pane id is at result.pane.pane_id.
  • use pane read for current output that already exists. use pane wait-output for future output you expect next.
  • --no-focus on split, tab create, and workspace create keeps your current terminal context focused.
  • without --label, workspace create keeps cwd-based naming and tab create keeps numbered naming.
  • --label on tab create and workspace create applies the custom name immediately.
  • if you are running inside herdr, the HERDR_ENV environment variable is set to 1.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.