Guide · Agent skill

How to use the Herdr agent skill: panes, config and updates

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Herdr is a terminal workspace manager that lets coding agents run side by side in panes, tabs and workspaces. The Herdr agent skill teaches your agent how to operate that tool, so you can ask it to start an agent in another pane, read what that agent is doing, or change your herdr setup in plain language. This guide explains what the skill does, how to install it, how to trigger it, and what it needs before you rely on it.

Herdr Terminal Workspace Managerdanielmiessler/LifeOS · MIT Download the skill

Quick start

1Install herdr. Install the herdr terminal workspace manager and confirm it runs on your machine. The skill cannot operate a tool that is not installed.
2Install the skill. Download the Herdr ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
3Open a herdr pane. Run your agent from inside a herdr pane. Control commands are designed to work only from there.
4Ask for a pane action. Make a natural request such as starting an agent in another pane, naming the target explicitly.
5Check the result. Ask the agent to read the other pane or list your agents, and confirm the outcome before acting on it.
6Run a freshness check. Run the freshness tool with Bun, using offline mode if you do not want network access, to see whether the install and config are current.

What the Herdr skill makes the agent do

The skill lets an agent drive herdr through its CLI and socket API. It can start an agent in a pane, prompt that agent, read its output, wait on it, and report what other agents in your workspaces are doing.

The skill does not contain command syntax of its own. It tells the agent to read the installed herdr binary for exact syntax, which helps avoid guessing at commands that may have changed between releases.

It also explains and edits the local herdr configuration, including keybindings, sidebar settings and agent-state integrations, and it can check your install against upstream for version and config drift.

Install the Herdr skill in Claude

Download the Herdr ZIP from this page, then choose one of these options. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

Personal: ~/.claude/skills/
Project only: .claude/skills/ inside the project
Claude apps: Settings → Capabilities → Skills

Check that herdr is ready before you use the skill

The skill needs herdr installed and runnable. Control commands only work from inside a herdr pane, because outside one the CLI can act on whichever pane you have focused.

Read-only work such as checking status, config or docs can run from anywhere. The freshness tool also needs Bun, plus curl and jq for filtering the config reference.

herdr installed and runnable
Bun, to run Tools/Freshness.ts
curl and jq, for filtering the config reference JSON
Network access to herdr.dev for online checks (optional; use offline mode to skip it)

bun ~/.claude/skills/Herdr/Tools/Freshness.ts [FLAGS]

Trigger the skill with natural requests

You do not need to name the skill. Phrases that mention herdr, a pane, a tab, a workspace or a worktree are enough, as are requests such as asking what your other agents are doing. The skill also responds to config, keybinding and sidebar questions, and to update or freshness checks.

Be specific about the target. The skill is built to act on an explicit pane rather than whatever happens to be focused.

Start an agent in a pane and ask it to review the diff.
Read the other pane and tell me what that agent is doing.
Why does this key do that in herdr?
Is herdr up to date?
Update herdr (the skill asks for confirmation first).

Safety notes: scripts, network and destructive actions

The skill runs scripts. Tools/Freshness.ts can run offline with a flag that avoids network access. Online checks reach herdr.dev. The skill is written so that anything that would stop the server, close panes you did not open, or answer another agent's dialog waits for your explicit yes.

Some actions take down every pane the server owns, including the session the agent runs in. The skill's own notes say to check the agent list first and get a yes before updating herdr, stopping the server, or restarting it.

Freshness checks are read-only; updating is a separate, confirmed step.
herdr update, herdr server stop and server restarts close all panes.
Do not use the skill for work outside herdr, such as in-harness subagents or the Hermes sidecar.

herdr agent list

Tips for getting reliable results

Ask the agent to read the herdr binary's own help or skill text rather than trusting memory. If a keybinding seems broken, the usual causes are a chord that only works through the kitty keyboard protocol, or a key that another tool claims system-wide.

If a theme or sidebar change does not appear on a remote machine, remember that those settings are read from the client's config.toml, not the server's.

Let the agent confirm config keys with herdr --default-config, though that list is incomplete.
Name the pane or workspace explicitly in every control request.
Run the offline freshness check after any herdr update to spot drift.

bun ~/.claude/skills/Herdr/Tools/Freshness.ts --json --offline

What people use it for

Start a second agent in a sibling pane to get an independent review of your current change, without moving your focus.
Check what other agents in your workspaces are doing without switching panes.
Find out why a herdr keybinding does not respond and which config key controls it.
Adjust the sidebar naming or width settings in your herdr config.
Confirm whether your herdr install and config match upstream after an update.

Frequently asked questions

Is the Herdr agent skill free to use?

The LifeOS item that contains this skill is released under the MIT licence. Herdr itself is licensed under AGPL, according to the skill's notes, so you should use it as an unmodified installed binary and check its own licence terms.

What do I need before installing the Herdr skill?

You need herdr installed and runnable. The freshness tool also needs Bun, plus curl and jq for filtering the config reference. Network access to herdr.dev is optional and only needed for online checks.

How do I install the Herdr skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Why does my herdr keybinding not work?

Keybindings that use a cmd chord only reach herdr through the kitty keyboard protocol, and a chord can be claimed by another tool system-wide. Ask the skill to explain the binding, which reads the live config file that causes it.

Does the skill run commands on my machine without asking?

Control commands run only from inside a herdr pane against an explicit target. Actions that would stop the server, close panes you did not open, or answer another agent's dialog wait for your explicit yes.

How does the Herdr skill compare with other ways to manage agent panes?

The source does not compare the skill with other tools or workflows. It is specific to herdr and its CLI, and it explicitly excludes in-harness subagents, the Helm terminal outside herdr, and the Hermes sidecar.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already run herdr and want your agent to start, prompt and read other panes, or to troubleshoot and check your herdr config. Pick something else if you do not use herdr, because the skill is specific to that tool and its CLI.

Download the skill