---
title: "@henryqw/pi-herdr"
seo:
  description: "Shared client for interacting with Herdr from Node.js tools and Pi extensions."
---

<div class="not-prose my-6 flex flex-wrap items-center gap-3"><span class="text-sm text-muted-foreground">v0.4.3</span><a href="https://www.npmjs.com/package/@henryqw/pi-herdr" aria-label="View @henryqw/pi-herdr on npm"><img alt="Monthly npm downloads" height="20" src="https://img.shields.io/npm/dm/%40henryqw%2Fpi-herdr?cacheSeconds=7200&amp;color=1d4ed8&amp;label=downloads&amp;labelColor=101828&amp;style=flat-square" width="144"></a></div>

Run Herdr CLI commands from Node through one thin client. Callers keep orchestration and command-specific checks.

## Why

- **Created for**: Call Herdr CLI commands from Node without duplicating wrapper logic across extensions.
- **Advantage**: One thin client keeps orchestration local. The Herdr CLI remains the source of truth for commands and response shapes.

## Install

```bash
npm install @henryqw/pi-herdr
```

## Use

```ts
import { createHerdrClient } from "@henryqw/pi-herdr";

const herdr = createHerdrClient(pi.exec.bind(pi));
const response = await herdr.json(["agent", "list"], { cwd: ctx.cwd });
```

| API | Result |
| --- | --- |
| `exec` | Validates string argv and returns the raw process result. |
| `run` | Requires a successful exit and returns stdout. |
| `json` | Requires a successful exit and parses a JSON object. |
| `hasHerdrErrorCode` | Detects structured CLI errors in stdout or stderr. |
| `startPiAgent` | Validates and builds the shared `agent start --kind pi --pane ... --` boundary. It retries structured `agent_pane_busy` responses allowed by the caller's result-aware policy, with a five-attempt limit, and returns the raw final result. |

Callers build Pi-specific arguments and validate responses. The client does not mirror the Herdr command catalog. Herdr remains the source of truth for supported commands and response shapes.