---
slug: "pi-tmux-thread"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/aweis89/pi-tmux-thread@main/README.md"
repo: "https://github.com/aweis89/pi-tmux-thread"
source_file: "README.md"
branch: "main"
---
# pi-tmux-thread

A small pi package that forks the current conversation into a separate pi process managed by tmux or [Herdr](https://herdr.dev).

The new conversation starts from `pi --fork <current-session>` so it can continue with the same context, but anything you do there stays out of the current thread.

## Install

```bash
pi install npm:pi-tmux-thread
# or from GitHub:
pi install git:github.com/aweis89/pi-tmux-thread
```

For local development:

```bash
pi install /path/to/pi-tmux-thread
```

Then reload pi:

```text
/reload
```

## Commands

### tmux

```text
/tmux [--select|-s] [split|window] [initial prompt]
/tmux:split [--select|-s] [initial prompt]
/tmux:window [--select|-s] [initial prompt]
/tmux:fork [--select|-s] [split|window] [initial prompt]
/tmux:select [split|window] [initial prompt]
```

- `split` opens a side-by-side tmux pane in the current tmux window. It requires pi itself to be running inside tmux.
- `window` opens a new tmux window. If pi is not already inside tmux, it creates/reuses a detached per-project tmux session and tells you how to attach.

### Herdr

```text
/herdr [--select|-s] [split|tab] [initial prompt]
/herdr:split [--select|-s] [initial prompt]
/herdr:tab [--select|-s] [initial prompt]
/herdr:fork [--select|-s] [split|tab] [initial prompt]
/herdr:select [split|tab] [initial prompt]
```

- `split` opens a side-by-side pane in the current Herdr tab.
- `tab` opens a new tab in the current Herdr workspace.
- Herdr commands require pi to be running in a Herdr-managed pane (`HERDR_ENV=1`).

For either multiplexer:

- `/tmux --select`, `/herdr --select`, or the `-s` shorthand starts the selectable fork workflow.
- The optional prompt is passed to the forked pi process as its first message.
- `--select`, `-s`, or the `:select` command opens a message picker showing only user messages and assistant text responses. The new thread includes the selected message and excludes every later message from the current thread.

Examples:

```text
/tmux:split investigate the failing test without changing this thread
/tmux:window brainstorm an alternate migration plan
/tmux:fork window review the current diff independently
/tmux:select window continue from the message I pick
/tmux:split --select try the other approach from this point
/tmux -s window continue from the message I pick
/herdr:split investigate in a sibling pane
/herdr:tab brainstorm an alternate migration plan
/herdr -s tab continue from the message I pick
```

## Agent tools

The package exposes two tools:

- `tmux_thread` opens a tmux split or window.
- `herdr_thread` opens a Herdr split or tab.

The agent should only use either tool when you explicitly ask for a separate multiplexer-managed pi thread. Set `forkFrom` to `select` to ask you which message should be the last included message.

## Notes

- tmux commands require `tmux` on `PATH`.
- Herdr commands require `herdr` on `PATH` and an active Herdr-managed pane.
- Commands are sent as portable shell syntax and work with fish as well as POSIX shells.
- Requires a persisted pi session; it cannot fork an ephemeral `--no-session` run.
- Inspired by the tmux management approach in `@romansix/pi-tmux` and the hidden side-thread workflow in `pi-btw`.