pi-tmux-thread

A small pi package that forks the current conversation into a separate pi process managed by tmux or Herdr.

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

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

For local development:

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

Then reload pi:

/reload

Commands

tmux

/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

/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:

/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.