pi-tmux-thread

Pi extension for forking conversations into tmux splits or windows

Packages

Package details

extensionskill

Install pi-tmux-thread from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-tmux-thread
Package
pi-tmux-thread
Version
0.1.1
Published
Jun 23, 2026
Downloads
306/mo · 15/wk
Author
aaronweisberg
License
MIT
Types
extension, skill
Size
17.7 KB
Dependencies
0 dependencies · 4 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/tmux-thread.ts"
  ],
  "skills": [
    "./skills"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-tmux-thread

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

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 [--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]
  • /tmux --select or /tmux -s starts the selectable fork workflow.
  • 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.
  • The optional prompt is passed to the forked pi process as its first message.
  • --select, -s, or /tmux:select opens a message picker showing only user messages and assistant text responses. The new tmux 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

Agent tool

The package also exposes a tmux_thread tool. The agent should only use it when you explicitly ask for a separate tmux-managed pi thread. Set forkFrom to select to ask you which message should be the last included message.

Notes

  • Requires tmux on PATH.
  • 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.