Quick start

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

herdr

Terminal window

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 copy it directly. 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 visible http:// or https:// URLs. On macOS, use Ctrl-click for Herdr-handled pane links while mouse capture is enabled; Cmd-click is only available through the terminal-native bypass path, such as Shift-Cmd-click or ui.mouse_capture = false.

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

Terminal window

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:

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

Terminal window

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.

Last updated Oct 08, 2026