pi-herdr

Pi-native tools for controlling Herdr layouts, terminal panes, and coding agents.

Install

pi install npm:@ogulcancelik/pi-herdr

Or add the package to ~/.pi/agent/settings.json:

{
  "packages": ["npm:@ogulcancelik/pi-herdr"]
}

The extension activates only when Pi runs inside a Herdr-managed pane with HERDR_ENV=1 and HERDR_PANE_ID set.

This package provides structured Pi tools only. It does not bundle Herdr's standalone agent skill. Install that skill separately when you want direct access to the complete installed CLI.

Execution model

Herdr exposes three distinct primitives:

• Layout organizes terminal locations. Workspaces contain tabs, and tabs contain panes.
• Pane controls a raw terminal containing a shell, test, server, build, log, or other ordinary process.
• Agent controls a recognized coding agent currently occupying a pane.

A pane exists independently of an agent. Starting an agent requires an existing pane at an available interactive shell prompt and never creates or changes layout.

The extension registers one tool for each primitive.

herdr_layout

Use herdr_layout to inspect and create workspaces, tabs, and pane topology.

Action	Description
current	Inspect the pane running the current Pi process
workspace_list	List workspaces
workspace_create	Create a workspace, first tab, and root pane
workspace_focus	Focus a workspace
tab_list	List tabs
tab_create	Create a tab and root pane
tab_focus	Focus a tab
pane_list	List panes in a workspace
pane_layout	Inspect pane geometry
pane_split	Split an existing pane

Creation defaults to the caller pane's foreground working directory and preserves UI focus. When pane_split omits a direction, the tool chooses right for a sufficiently wide pane and down for a narrow or tall pane.

Workspace, tab, and pane IDs are opaque. Always use IDs returned by Herdr instead of constructing them.

herdr_pane

Use herdr_pane for ordinary commands and intentional raw terminal control.

Action	Description
get	Inspect a pane
run	Submit a shell command atomically with Enter
read	Read terminal output
wait_output	Wait for literal or regular-expression output
send_text	Send literal text without Enter
send_keys	Send logical terminal keys
close	Close a pane other than the pane running Pi

wait_output searches existing output immediately before waiting for future output. Use recent-unwrapped for logs and transcripts.

Pane actions do not validate coding-agent identity or interpret agent lifecycle. Use herdr_agent when a pane contains a recognized coding agent.

herdr_agent

Use herdr_agent to control a recognized coding agent by unique live name or by its hosting pane ID.

Action	Description
list	List recognized agents
get	Inspect an agent
start	Start a supported agent in an existing available shell pane
prompt	Submit a prompt and optionally wait for settlement
wait	Wait for lifecycle state
read	Read the resolved agent terminal stream
send_keys	Send validated logical keys to the agent UI
focus	Focus the agent's pane
rename	Set or clear a live agent name

Agent targets accept a unique live agent name or the pane ID currently hosting that agent. They do not accept terminal IDs or bare agent-kind labels.

Lifecycle states are:

• working: actively processing
• blocked: waiting for approval or an answer
• done: ready after unseen background work completed
• idle: ready and considered seen
• unknown: present, but lifecycle cannot be classified confidently

prompt waits by default and settles on the first idle, done, or blocked state unless until narrows the accepted states. A prompt submitted from a non-working state must produce an observed lifecycle change within five seconds or Herdr returns agent_prompt_stalled.

Typical workflows

Start a coding agent in a sibling pane:

{ "action": "pane_split" }

Use the returned pane ID:

{
  "action": "start",
  "name": "reviewer",
  "kind": "codex",
  "pane": "w1:p2"
}

Prompt it and wait for settlement:

{
  "action": "prompt",
  "target": "reviewer",
  "prompt": "Review the current diff and report only actionable findings.",
  "timeout": 120000
}

Read the result:

{
  "action": "read",
  "target": "reviewer",
  "source": "recent-unwrapped",
  "lines": 120
}

For an ordinary command, split a pane with herdr_layout, submit the command with herdr_pane run, then use herdr_pane wait_output or herdr_pane read.

Invocation policy

The tools are opt-in. Pi uses them only when the user explicitly mentions Herdr or asks to inspect or control Herdr. Installing this package does not turn general background work or delegation into a Herdr workflow.

The default topology is a sibling pane in the caller's current tab and working directory. Focus remains with the user. Another tab, workspace, worktree, or working directory is used only when requested.

Output limits

Read output is truncated to the last 2,000 lines or 50KB, whichever is reached first.

Full-screen agents may render through the terminal's alternate screen. Rows that leave that screen do not enter Herdr's host scrollback. If increasing lines does not reveal the complete response, ask the agent to write its response to a temporary Markdown file and read that file directly.

Requirements

• Pi 0.80 or newer
• Herdr 0.7.5 or newer
• Pi running inside a Herdr pane

License

MIT