@deevus/pi-zmx

A pi extension that executes shell commands inside persistent zmx sessions.

Features

• Persistent sessions — filesystem effects, background processes, and exported env vars survive across tool calls
• Non-blocking — zmx_run sends commands and returns immediately; use zmx_wait when you need to block
• Human-in-the-loop — start a process, prompt the user to attach and enter a password or interact, then continue
• Auto session naming — defaults to the pi session display name if set; otherwise requires an explicit session name

Requirements

zmx must be installed and on your PATH:

brew install neurosnap/tap/zmx

Or download a binary directly from zmx.sh.

Install

pi install npm:@deevus/pi-zmx

Tools

Tool	Description
zmx_run	Send a shell command to a zmx session (non-blocking)
zmx_wait	Wait for session tasks to complete
zmx_history	View recent scrollback from a session
zmx_list	List active zmx sessions
zmx_kill	Kill one or more zmx sessions
zmx_attach	Get instructions for manually attaching to a session

Commands

Command	Description
/zmx	Interactive session manager (attach / create / kill)

Usage

Basic

zmx_run(session="my-project", command="npm test")
zmx_wait(session="my-project")
zmx_history(session="my-project", lines=50)

Human-in-the-loop (e.g. password prompt)

zmx_run(session="my-project", command="sudo apt update")
zmx_attach(session="my-project")
# → tells the human to run: zmx attach my-project
# → human enters password and detaches with Ctrl+\
zmx_wait(session="my-project")
zmx_history(session="my-project")

License

MIT