pi-mux

Run multiple pi sessions concurrently in one terminal via tmux

Packages

Package details

extension

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

npm repohome report
$ pi install npm:pi-mux
Package
pi-mux
Version
0.1.3
Published
Jul 1, 2026
Downloads
309/mo · 33/wk
Author
leohenon
License
MIT
Types
extension
Size
38.4 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

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

README

pi-mux

npm tmux

Pi session multiplexer. Run multiple Pi sessions in one terminal via tmux. Switch between them without killing the one you're leaving.

demo

Install

pi install npm:pi-mux

Requires tmux 3.0+ and pi ≥ 0.74.0. Run Pi inside any tmux session. Outside tmux, pi-mux is a no-op.

Commands

/switch

Pick a session and jump to it. Whatever you were in stays alive in the background. (Unlike /resume, which closes it.)

A spinner marks sessions currently working.

/new

Start a fresh session without closing the one you're in.

/fork

Fork your current session at any previous message, the original stays open.

/mux

Lists every Pi running on your machine. Press Enter to jump to an open Pi or bring a backgrounded one forward; kill the ones you're done with.

Each row shows cwd, session name, and a tag:

  • [current] — the Pi you're typing in.
  • [backgrounded] — parked in _pi-mux, brought back via /switch.
  • [open] — running in another tmux pane you can navigate to.
  • [... · busy] if mid-turn.

/mux-status

Print whether pi-mux is active in the current Pi session.

How it works

pi-mux keeps one extra tmux session, _pi-mux, holding backgrounded Pis as detached windows. Spawning (/new, /fork, /switch to a non-live session) creates a detached window in the pool, starts Pi there, and swaps its pane into your visible pane. The Pi you just left is now in the pool, still running.

tmux
├── your session
│   └── visible pane  ←── pi-mux swaps panes in & out
│
└── _pi-mux            (hidden, auto-managed)
    ├── window: Pi session A
    ├── window: Pi session B
    └── window: Pi session C

When a Pi exits, its window closes; tmux auto-destroys the pool when empty. Heartbeat files in ~/.pi-mux/heartbeats/ track each live Pi, so /switch and /mux can show which sessions are alive and which are busy.

Backgrounded Pis idle at ~0% CPU and use memory equivalent to one Pi session each.

[!TIP] Hide _pi-mux from tmux ls with: alias tls="tmux ls 2>/dev/null | grep -v '^_pi-mux:'". If the pool has leftover windows after a crash, run tmux kill-session -t _pi-mux to clear.

Contributing

Bug reports, feature ideas, and PRs welcome — see CONTRIBUTING.md.

License

MIT