https://github.com/deevus/pi-zmx
Execute shell commands in persistent zmx sessions from pi
https://github.com/deevus/pi-zmx
Last synced: 13 days ago
JSON representation
Execute shell commands in persistent zmx sessions from pi
- Host: GitHub
- URL: https://github.com/deevus/pi-zmx
- Owner: deevus
- License: mit
- Created: 2026-04-24T07:40:59.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-21T03:54:09.000Z (29 days ago)
- Last Synced: 2026-05-21T10:12:52.146Z (29 days ago)
- Language: TypeScript
- Size: 43 KB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @deevus/pi-zmx
A [pi](https://github.com/badlogic/pi-mono) extension that executes shell commands inside persistent [zmx](https://zmx.sh) 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](https://zmx.sh) must be installed and on your `PATH`:
```bash
brew install neurosnap/tap/zmx
```
Or download a binary directly from [zmx.sh](https://zmx.sh/#binaries).
## Install
```bash
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