Quick start

Preview build 2026-10-14-fbd2ae23927f, published from fbd2ae23927f. Stable docs remain at /docs/.

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

herdr

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

Create a workspace

When a session has no workspaces, Herdr 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.

Use the mouse

Herdr 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 Herdr. 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 Herdr receives a Ctrl-release event; some terminals only report modifier changes with mouse movement.

With ui.mouse_capture = true (the default), Herdr 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 Herdr 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 Herdr plugins. Disabling capture also disables Herdr’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. Herdr 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 herdr pane input --current --right-click pane inside it. Right-click the pane frame to reopen Herdr’s menu.

Run an agent

Start your coding agent in a pane:

claude

Or codex, pi, opencode, or any other supported agent. Herdr 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

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 Herdr to see every active binding, and prefix+[ to copy from the keyboard in copy mode.

Detach and come back

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

To end the session and stop its panes:

herdr server stop

Where next

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