Quick start

Next docs describe unreleased work from master. Stable docs remain at /docs/.

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

pk-herdr

PK-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, PK-Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace; this keeps agent state readable in the sidebar.

Use the mouse

PK-Herdr is mouse-native, so start by clicking. Click panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. When OMP, Claude, or Codex is idle at its prompt, choose Summarize session to ask that agent for a concise handoff summary using its current conversation context. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.

Summarize session submits into the agent’s current prompt, so send or clear any unsent draft first.

Ctrl-click opens pane links when your terminal sends the modified click to PK-Herdr. This works for OSC 8 hyperlinks and visible http:// or https:// URLs. On macOS, use Ctrl-click for PK-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.

Run an agent

Start your coding agent in a pane:

claude

Or codex, pi, opencode, or any other supported agent. PK-Herdr detects it automatically. The sidebar shows whether each agent is working, blocked, done, or idle — across every workspace, 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 across spaces	ctrl+pagedown / ctrl+pageup or prefix+n / prefix+p
Workspace navigation	prefix+w
New workspace	prefix+shift+n
Detach client	prefix+q

New to the prefix idea? Keyboard explains what it is, why multiplexers use one, and how to go prefix-free. Press prefix+? inside PK-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 PK-Herdr server and every agent keep running. Run pk-herdr again to reattach to the same session.

To actually end the session and stop its panes:

pk-herdr server stop

Where next

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