pi-tmux-session-picker

pi-tmux-session-picker shows live Pi processes in a tmux popup. Select a row to switch to its pane.

The extension publishes a small lifecycle state to pane-scoped tmux options. The picker reads these options without a daemon or pane scraping.

Requirements

Install these programs:

• Pi 0.84.1 or newer
• Node.js 22.19.0 or newer
• tmux 3.2 or newer
• fzf

Pi must run inside tmux. The extension does nothing outside tmux.

Install

Install a local checkout:

pi install /absolute/path/to/pi-tmux

When an npm release is available, install it with this command:

pi install npm:pi-tmux-session-picker

Restart each active Pi process after installation. You can also run /reload in each process.

Configure tmux

Add this binding to ~/.tmux.conf. The package also includes it in tmux.conf:

bind-key p if-shell -F '#{@pi_tmux_picker_command}' {
  if-shell 'eval "$(tmux show-option -gv @pi_tmux_picker_command) --has-sessions"' {
    display-popup -E -w 80% -h 60% \
      "tmux show-option -gv @pi_tmux_picker_command | sh"
  } {
    display-message "No live Pi sessions found"
  }
} {
  display-message "pi-tmux-session-picker is not loaded"
}

Reload the tmux configuration:

tmux source-file ~/.tmux.conf

Press the tmux prefix, then press p. Select a Pi process with fzf and press Enter.

A ● marks a session whose metadata changed while its tmux window was not visible. Initial registration is treated as viewed. Later updates are also treated as viewed while the window is active in an attached tmux session. The marker clears after the picker successfully switches to that pane. Viewed state is shared by all tmux clients; switching panes by another method does not clear it.

Elapsed values such as 12s, 4m, 2h, or 3d show the time since the latest metadata update. They are snapshots calculated when the picker opens and do not update while fzf remains open.

The picker shows a Pi session name only when one was explicitly assigned. It hides generated Pi <session-id> fallback names.

If no Pi process is available, tmux shows No live Pi sessions found. It does not open an empty popup.

The extension sets @pi_tmux_picker_command when an instrumented Pi process starts. The option contains the installed picker path.

Status values

Version 1 uses five lifecycle events:

Event	Popup label	Meaning
session_start	READY	The Pi session is ready.
agent_start	WORKING	Pi processes a request.
needs_input	NEEDS INPUT	An rpiv questionnaire waits for input.
agent_end	DONE	Pi completed retries, compaction, and queued work.
session_shutdown	Not shown	The extension removes the pane metadata.

The extension maps Pi agent_settled to agent_end. It does not use Pi's lower-level agent_end event.

rpiv integration

The NEEDS INPUT state is optional. It requires an extension that emits this event:

const askUserBlockedEvent = "rpiv:ask-user:blocked";

pi.events.emit(askUserBlockedEvent, { active: true });
pi.events.emit(askUserBlockedEvent, { active: false });

active: true sets needs_input. active: false restores agent_start until Pi emits agent_settled.

Malformed events do not change the current state.

Picker order

The popup places unseen (●) rows above viewed rows. Within each group, it places the most recently updated rows first. Rows with the same update time use this lifecycle priority:

1. NEEDS INPUT
2. WORKING
3. READY
4. DONE

Rows with the same viewed status, update time, and lifecycle state use the Pi session name and pane ID for stable order.

Each row also shows these values:

• Elapsed time since the latest metadata update
• tmux session name
• tmux window index and name
• Explicit Pi session name, when assigned
• Working directory

When the picker opens, it sizes the tmux session and window columns to the longest visible values. The columns have no fixed limits and values are not truncated.

Scope and privacy

The picker lists instrumented top-level Pi processes in the current tmux server. It does not search other tmux socket paths. Pi subagent children are excluded because they inherit the parent process's tmux pane instead of owning a pane.

The extension stores only these pane options:

@pi_tmux_version
@pi_tmux_pid
@pi_tmux_event
@pi_tmux_session_id
@pi_tmux_session_name
@pi_tmux_cwd
@pi_tmux_updated_at
@pi_tmux_viewed_at

The extension does not store prompts, tool arguments, questionnaire answers, or event payloads.

The picker checks each recorded PID. It hides a row when the process no longer exists.

Development

Install the development dependencies:

npm install

Run all checks:

npm run check

Run the package check:

npm pack --dry-run

The test suite uses an isolated tmux socket. The test removes its tmux server after completion.

License

MIT