Skip to content

Quick start

If Herdsman is not installed yet, see Install. Then start Herdsman from any project directory:

Terminal window
herdsman

Herdsman launches or attaches to your default background session. You do not manage sockets. If you detach, agents keep running.

When a session has no workspaces, Herdsman opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace to keep agent state readable in the sidebar.

Herdsman is mouse-native, so start by clicking panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard. Double-click a token to select it, or hold the second press and drag to extend the selection by whole words. Both gestures copy when you release the mouse. Copying does not require Ctrl+C.

Ctrl-click opens pane links when your terminal sends the modified click to Herdsman. This works for OSC 8 hyperlinks and http:// or https:// URLs, including wrapped links whose beginning or end is outside the visible area. Hold Ctrl and move the pointer over a link to underline its visible segments. Hover highlighting clears when you move away, the pane content changes, or Herdsman receives a Ctrl-release event; some terminals only report modifier changes with mouse movement.

With ui.mouse_capture = true (the default), Herdsman handles Ctrl-clicks. Matching enabled plugins run first. A handler launch failure shows an error and stops. Unmatched http:// and https:// links open in the default browser on the machine running the Herdsman client. Other links need a matching plugin. Explicit hyperlinks are not advertised to the outer terminal in this mode, so native bypass clicks on labeled links are unavailable, including Command-click on macOS.

With ui.mouse_capture = false, explicit hyperlinks are passed to the outer terminal. Use its normal link shortcuts and warnings. These clicks do not invoke Herdsman plugins. Disabling capture also disables Herdsman’s mouse controls, including clicking tabs and dragging split borders.

Windows Terminal can still intercept URLs it detects in visible text. For reliable plugin priority on those URLs, set "experimental.detectURLs": false in Windows Terminal’s settings.json. This setting applies to all Windows Terminal profiles. Herdsman does not change it.

If you configure ui.right_click_passthrough_modifier, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps. To make normal right-click go to one pane app, choose Send right-clicks to pane from that pane’s menu or run herdsman pane input --current --right-click pane inside it. Right-click the pane frame to reopen Herdsman’s menu.

Start your coding agent in a pane:

Terminal window
claude

Or codex, pi, opencode, or any other supported agent. Herdsman detects it automatically. Across every workspace, the sidebar shows whether each agent is working, blocked, done, or idle, so you always know which project needs you.

Keyboard control is optional; the mouse covers everything. Press ctrl+b to enter prefix mode, then press an action key.

Common actions:

Action Key
Split right prefix+v
Split down prefix+minus
New tab prefix+c
Next / previous tab prefix+n / prefix+p
Workspace navigation prefix+w
New workspace prefix+shift+n
Detach client prefix+q

If the prefix idea is new to you, Keyboard explains what it is, why multiplexers use one, and how to go prefix-free. Press prefix+? inside Herdsman to see every active binding, and prefix+[ to copy from the keyboard in copy mode.

Press prefix+q or simply close your terminal window. The Herdsman server and every agent keep running. Run herdsman again to reattach to the same session.

To end the session and stop its panes:

Terminal window
herdsman server stop
  • Concepts — the workspace, tab, pane, and agent model in two minutes.
  • How to work with Herdsman — local, SSH, phone, and herdsman --remote workflows.
  • Agents — supported agents, detection, and integrations that improve state accuracy.
  • Configuration — keybindings, themes, notifications, and everything else.