Pi Herdr Sidetrack

Clone the active Pi conversation into a focused right-hand Herdr pane with one command:

/sidetrack <prompt>

The parent conversation stays on its current session and branch, and may keep working. /sidetrack snapshots the current completed tip immediately (it does not wait for the parent to go idle), opens a separate Pi session file for that branch, then processes your prompt in a new pane.

Shared checkout: A sidetrack is a conversation clone, not an isolated workspace. Parent and sidetrack use the same checkout and can see or change the same files.

Requirements

• Node.js 22.19.0 or newer
• Pi in interactive TUI mode
• Herdr, with Pi started through Herdr
• A persisted Pi conversation
• At least one completed assistant response on the currently selected branch

If you navigate with /tree, wait for an assistant response on the selected branch before creating a sidetrack.

Installation

Install for your Pi user:

pi install npm:@maxedapps/pi-herdr-sidetrack

Try it for one run without installing permanently:

pi -e npm:@maxedapps/pi-herdr-sidetrack

Start that Pi process through Herdr. Update or remove the package with:

pi update --extension npm:@maxedapps/pi-herdr-sidetrack
pi remove npm:@maxedapps/pi-herdr-sidetrack

Usage

Start from a persisted Pi conversation, then enter a text prompt:

/sidetrack explore a smaller implementation without changing the parent conversation

/sidetrack --compare the two error-handling approaches

/sidetrack @README.md suggest a clearer opening section

The new pane:

• opens to the right at a 50/50 split and receives focus;
• uses the same checkout and working directory as the parent;
• has an independent Pi session file and session name;
• inherits the selected branch's conversation, model changes, thinking-level changes, compaction context, labels, and session information;
• processes the supplied prompt during interactive startup, including prompts beginning with -- or @.

The parent session file, active branch, and conversation remain unchanged by cloning. In-flight assistant text that has not finished a message yet is not part of the snapshot—only completed session entries up to the current tip are copied. There is no automatic synchronization between the two conversations afterward.

Compatibility and errors

Herdr 0.7.4/protocol 16 is live-validated. Protocol 17 is selected through protocol negotiation and covered by integration tests, with live validation only when a compatible binary is available. No broader Herdr release range is implied.

Unsupported protocols are rejected before a pane or child session is created. This fail-closed behavior avoids guessing at future Herdr request formats.

Outside Herdr, the command is not registered. UI-capable Pi modes show this notice once:

Herdr sidetrack inactive: start Pi through Herdr to enable /sidetrack.

Other errors explain when Pi must run in its interactive TUI, the prompt is empty, the parent session is not persisted, the selected branch has no saved leaf or completed assistant response, or the Herdr protocol is unsupported.

If cloning succeeds but Herdr does not confirm the launch, the error includes the exact preserved child-session path. A pane may already have been created after a timeout, so the package does not delete the clone or attempt automatic cleanup.

Limitations

• Prompts are text-only; images and attachments are not copied into the initial sidetrack prompt.
• There is no Git worktree or filesystem isolation. Both conversations share the same checkout and files.
• Parent and sidetrack sessions do not exchange messages, results, lifecycle state, or later conversation changes.
• Pane direction, ratio, focus, and cleanup are not configurable.
• Unknown future Herdr protocols are rejected until support is explicitly added and verified.

Security

Pi packages and extensions execute with the current user's full system permissions. Install this package only from a source you trust, and use it only in trusted repositories and Herdr workspaces. Remember that both panes can modify the same working tree.

License

MIT