pi-herdr-fork

pi-herdr-fork is a source-only Pi extension that adds /fork-herdr for Herdr.

Choose a finalized user prompt and continue from that branch point in a new, focused Herdr pane. The parent Pi process—including an active model response or tool call—keeps running in its original pane and session.

Features

• Uses Pi's native user-message fork selector.
• Runs immediately while the parent is streaming or using tools.
• Opens a focused 50/50 pane to the right of the exact calling Herdr pane.
• Creates a separate child session ID and JSONL file.
• Copies only the selected prompt's finalized ancestor chain.
• Restores the selected prompt in the child editor without submitting it.
• Keeps parent and child session writes isolated.
• Validates Herdr client/server protocol compatibility before creating resources.
• Cleans up only resources known to be owned after definite launch failures.
• Has no production npm dependencies.

Requirements

The initial supported environment is:

• macOS or another POSIX shell environment
• Node.js >=22.19.0
• Pi 0.84.0
• Herdr 0.7.4, with client and server using protocol 16
• Herdr's official Pi integration

The extension intentionally rejects non-TUI use, execution outside Herdr, ephemeral or unmaterialized sessions, incompatible Herdr protocols, and sessions without a forkable user message.

Install

Install from npm for the current user:

pi install npm:pi-herdr-fork

Install for the current project instead:

pi install -l npm:pi-herdr-fork

To try the extension for one parent process without installing it:

pi -e npm:pi-herdr-fork

For end-to-end forking, install the package rather than using only pi -e. The newly launched child Pi must also load the extension's bootstrap handler.

Install a local checkout during development:

pi install /absolute/path/to/pi-herdr-fork

Pi packages execute with full system access. Review third-party extension source before installation.

Usage

1. Start Pi in a Herdr pane with a persisted session.

2. Enter:

   /fork-herdr

3. Choose a non-empty, finalized user message.

The newest message is selected initially. Herdr splits the calling pane to the right at ratio 0.5, focuses the child pane, and starts Pi with a distinct session. The child contains the selected message's ancestors but excludes the selected prompt itself and sibling branches. The selected prompt appears in the child editor so you can modify or submit it.

The command does not wait for idle, abort, steer, replace, or mutate the parent session. Partial assistant output from an in-progress response is not copied because only finalized session entries are forkable.

Session and workspace behavior

Parent and child own separate absolute session files and can append independently. The child session header records the source JSONL as parentSession. If Pi defers a no-assistant child snapshot, the extension materializes the complete generated header and retained ancestry before launching the child.

Both panes use the same working directory. Files, build output, processes, uncommitted changes, and checkout state are shared. /fork-herdr provides session isolation—not filesystem or Git worktree isolation.

If Herdr reports an ambiguous split or launch result, the extension preserves the possible child pane/session and reports their identifiers instead of risking destructive cleanup.

Updating and removing

pi update npm:pi-herdr-fork
pi remove npm:pi-herdr-fork

Agent and maintainer reference

Package contract

• Pi manifest: package.json#pi.extensions loads ./src/index.ts.
• Registered command: exactly fork-herdr.
• Runtime dependencies: none; Pi is a peer dependency supplied by the host.
• Child command: pi --session "$PI_HERDR_FORK_SESSION" in the new Herdr pane.
• Supported Herdr protocol: exactly 16.
• Source and child session paths must be distinct absolute sibling JSONL paths.

Safety invariants

Agents modifying this extension must preserve these guarantees:

1. Never call parent session controls such as waitForIdle, abort, fork, newSession, or switchSession from /fork-herdr.
2. Never mutate or share the live parent SessionManager; create the child through a separately opened manager.
3. Never include the selected prompt or sibling branches in the child JSONL.
4. Never pass prompt text through process arguments, environment variables, or error messages.
5. Target the calling pane explicitly with HERDR_PANE_ID; do not rely on focused-pane state.
6. Treat timeouts, malformed responses, and uncertain delivery as ambiguous. Preserve resources unless failure and ownership are definite.
7. Remove only a validated, owned child session and only close the pane returned by the successful split.
8. Consume child bootstrap markers once and only when child path and parentSession match.

Cross-process bootstrap

The split passes only these markers to the child pane:

• PI_HERDR_FORK_SESSION: generated child session path
• PI_HERDR_FORK_SOURCE: source session path
• PI_HERDR_FORK_ENTRY: selected source entry ID

On the matching child's first session_start, the extension reads the selected message from the source JSONL, pre-fills the editor, and removes the markers from the process environment. Unrelated sessions and later reloads are ignored.

Development

npm install
npm run check

Additional release checks:

printf '%s\n' '{"id":"commands","type":"get_commands"}' \
  | pi --mode rpc --no-session --offline --no-extensions -e .
npm pack --dry-run --json

The test suite uses Pi's real SessionManager in temporary directories and fakes the UI and Herdr process boundary. A release should also be tested manually in a disposable persisted Pi conversation inside Herdr, including invocation during a visibly long-running parent turn.

Publishing

The npm package name is pi-herdr-fork. Publishing requires an authenticated npm account with two-factor authentication or an appropriately configured granular access token.

npm login
npm whoami
npm run check
npm pack --dry-run
npm publish

The package is unscoped and configured for public access. npm package names are first-come, first-served, so verify availability immediately before the first publish. Published versions are immutable; increment version and update CHANGELOG.md for each later release.

License

MIT © 2026 Maximilian Schwarzmüller