pi-jump

Jump between running pi sessions across tmux windows — without Ctrl-B w hunting.

A pi coding agent extension that adds /jump: a picker of every live pi session on your tmux server. Hit Enter, you're there.

https://github.com/sagarsrc/pi-jump/releases/download/v2.1.2/pi-jump-demo.mp4

╭──────────────────── ◈ pi-jump ────────────────────╮
│ ❯ med█                                            │
│───────────────────────────────────────────────────│
│ → ● sidequest      │ main:1 │  2m ago [current]   │
│   ● media-project  │ work:1 │ 37m ago             │
│   ○ cryptobot      │  fun:1 │  3h ago             │
│┄┄┄┄┄┄┄┄┄ preview: media-project (work:1) ┄┄┄┄┄┄┄┄┄│
│   $ npm run dev                                   │
│   ✓ built in 380ms                                │
│   ➜ Local: http://localhost:5173                  │
│                                                   │
│ ↑↓ move · type to filter · ⏎ jump · esc close     │
╰───────────────────────────────────────────────────╯

• ● your current session — everything else is ○
• Scan-detected sessions (pi running without the extension) appear dimmed
• Columns: session name │ tmux session:window (never truncated) │ cwd (~ = home) │ age — columns adapt to width, always aligned
• Preview: live tail of the highlighted pane, with the target's status line cropped out

Why

You run pi in several tmux windows. Switching means Ctrl-B w and guessing which anonymous window holds the session you want. pi-jump knows: every pi self-registers its tmux coordinates on startup, and /jump switches your tmux client straight to the right session and window.

Install

# from git (pinned ref recommended)
pi install git:github.com/sagarsrc/[email protected]

# or from npm
pi install npm:pi-jump

Then /reload in any running pi (or start a new one). Requires pi to run inside tmux.

Usage

/jump

Pick a session → your tmux client switches to it. Dead sessions are pruned automatically; if your target dies mid-pick, the picker re-opens with a fresh list.

v2.1 picker: a real modal that floats over your chat — bordered box, highlighted selection, live preview of the highlighted pane (its status line cropped out so you never confuse it with yours).

v2.0 picker superpowers:

• Fuzzy filter — just start typing; matches session names, directories, and tmux session names
• Live preview — the highlighted session's pane content renders below the list, refreshing as you move the cursor

Name your sessions with pi's built-in /name — the picker shows the name instead of the directory.

How it works

• Self-registry: on session_start, each interactive pi writes its tmux coordinates (session, window, pane id, resolved via $TMUX_PANE) to ~/.pi/agent/tmux-registry.json. Headless pi's (pi -p, subagents) never register — no noise.
• Scan fallback: panes running pi without the extension are discovered by walking the process tree (ps → comm == "pi" → lsof for cwd).
• Jump: tmux switch-client -t <session>:<window>. Entries are deduplicated per pane and pruned when panes die.

Registry file: ~/.pi/agent/tmux-registry.json — safe to delete; it rebuilds.

Development

npm install
npm test        # 43 unit tests (vitest)
npm run typecheck

# load locally without installing
pi -e ./index.ts

Roadmap

• Kill session / open new session from the picker
• Fuzzy filter
• Status widget with session count

License

MIT © Sagar Sarkale