Tmux Branch Pi extension

A Pi coding agent extension that branches the current Pi session into a new tmux pane.

The extension creates an independent branch of the current persisted Pi session, then opens that branch in a new tmux split by running:

pi --session <branched-session-file>

Install

Install from GitHub:

pi install git:github.com/andrii-k6a/pi-tmux-branch

Try it without installing:

pi -e git:github.com/andrii-k6a/pi-tmux-branch

For regular use, install the extension. Temporary -e packages may be resolved again in each branched Pi process, so installation is faster and more reliable.

When Pi is started with temporary extension flags, the extension passes the common forms through to branched panes: -e <spec>, --extension <spec>, and --extension=<spec>. Repeated flags are preserved in order. For example, a session started with:

pi -e git:github.com/andrii-k6a/pi-tmux-branch

branches into a pane that runs an equivalent command:

pi -e git:github.com/andrii-k6a/pi-tmux-branch --session <branched-session-file>

Only explicit temporary extension flags from the current process are copied. Installed global/project extensions are discovered by Pi as usual, and short-option clusters such as -ex are not expanded.

Requirements

• tmux

Usage

Run one of the /tmux-branch-* commands or use a shortcut. The extension branches the current Pi session and opens the branch in a new tmux pane.

If the current Pi conversation has not been persisted yet, such as immediately after starting Pi before the first assistant response, the extension opens a fresh Pi conversation in the requested tmux pane instead of branching. If the current Pi process was started with --no-session, the fresh pane also uses --no-session.

Command handlers wait until Pi is idle before branching. Shortcut handlers require Pi to already be idle; if Pi is busy, the extension displays an error notification.

How it works

1. Verifies Pi is running with an interactive UI inside tmux.
2. If the current session is persisted and has a leaf, opens it with SessionManager.open(...), creates a branched session using createBranchedSession(leafId), and starts Pi with --session <branched-session-file>.
3. Runs tmux split-window with the requested direction.

The extension intentionally creates the branched session directly instead of using ctx.fork(), because ctx.fork() would replace the current runtime/pane. This also means Pi's normal fork lifecycle events are not emitted in the original pane: session_before_fork, session_shutdown, and session_start do not run for this branch operation.

Controls

Commands

| Command | Behavior | | --- | --- | | /tmux-branch-right | Branch the current Pi session into a new tmux pane on the right | | /tmux-branch-left | Branch the current Pi session into a new tmux pane on the left | | /tmux-branch-down | Branch the current Pi session into a new tmux pane below | | /tmux-branch-up | Branch the current Pi session into a new tmux pane above |

Default shortcuts

By default, Vim-style shortcuts mirror tmux pane navigation: h/j/k/l = left/down/up/right.

| Shortcut | Behavior | | --- | --- | | Ctrl+Shift+L | Branch the current Pi session into a new tmux pane on the right | | Ctrl+Shift+H | Branch the current Pi session into a new tmux pane on the left | | Ctrl+Shift+J | Branch the current Pi session into a new tmux pane below | | Ctrl+Shift+K | Branch the current Pi session into a new tmux pane above |

Note: your terminal and tmux configuration must pass Ctrl+Shift+<letter> key combinations through to Pi distinctly for the shortcuts to work.

Configuration

Slash commands are always registered. Shortcuts are configured with settings.json under the extension's Pi config directory:

• global: ~/.pi/agent/pi-tmux-branch/settings.json
• project-local: <project>/.pi/pi-tmux-branch/settings.json

Project-local configuration uses whole-file precedence over global configuration. If a project-local settings file exists, the global settings file is ignored; settings are not deep-merged.

Commands only

Disable shortcut registration while keeping slash commands available:

{
  "shortcutsEnabled": false
}

Default Vim-style shortcuts

This is the default when no configuration file exists. To be explicit:

{
  "shortcutsEnabled": true
}

Custom shortcut bindings

Use an object to override one or more directions. Missing directions keep their default Vim-style shortcut. Set a direction to false or null to leave that direction command-only.

{
  "shortcuts": {
    "right": "ctrl+alt+l",
    "left": "ctrl+alt+h",
    "down": "ctrl+alt+j",
    "up": "ctrl+alt+k"
  }
}

Development

From this repository:

npm install
npm run typecheck
pi -e .