---
slug: "maxedapps-pi-herdr-sidetrack"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/maxedapps/pi-herdr-sidetrack@main/README.md"
repo: "https://github.com/maxedapps/pi-herdr-sidetrack"
source_file: "README.md"
branch: "main"
---
# Pi Herdr Sidetrack

Clone the active Pi conversation into a focused right-hand [Herdr](https://herdr.dev) pane with one command:

```text
/sidetrack <prompt>
```

The parent conversation stays on its current session and branch. The sidetrack receives a separate Pi session file containing the exact selected branch, then immediately processes your prompt and remains interactive.

> **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](https://github.com/earendil-works/pi-mono) in interactive TUI mode
- [Herdr](https://herdr.dev), 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:

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

Try it for one run without installing permanently:

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

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

```bash
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:

```text
/sidetrack explore a smaller implementation without changing the parent conversation
```

```text
/sidetrack --compare the two error-handling approaches
```

```text
/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. 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:

```text
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](https://github.com/maxedapps/pi-herdr-sidetrack/tree/HEAD/LICENSE)