name: working-with-zmx description: >- Manages persistent terminal sessions for background processes, dev servers, and long-running tasks. Use when the user mentions running something in the background, starting a dev server, running commands over SSH in a persistent session, or needs an alternative to tmux/screen for session multiplexing. license: GPL-3.0-or-later metadata: author: Amolith amolith@secluded.site

• zmx attach <sess-name> [command...]: Create a session and attach to it (interactive. likely never use this; it's for your human operator).
• zmx run <sess-name> [-d] [--fish] [command...]: run command in session, creating the session if it doesn't exist. -d detaches and returns immediately. --fish is required when the login shell is fish.
• zmx list [--short]: prefer --short
• zmx kill <sess-name>... [--force]
• zmx detach <sess-name>: detach all clients from a session.
• zmx history <sess-name>: print session history in plaintext
  • --vt adds VT escape sequences and --html produces HTML. Prefer plaintext.
• zmx wait <sess-name>...: Block until a detached run task completes.
• zmx tail <sess-name>...: Follow session output in real time.
• zmx write <sess-name> <file_path>: Write stdin to a file path inside the session (works over SSH).

Starting sessions

Check for existing sessions to avoid duplicates with zmx list --short. Always use unique session IDs:

openssl rand -hex 3 # in one tool call
## abc123
# in subsequent tool calls
zmx run "abc123-dev" -d deno run --allow-all server.ts
zmx history "abc123-dev" | tail -50

Running commands in the foreground

The simplest situation:

zmx run abc123-dev go build ./...
# ... output ...

Detaching

First check the user's shell with getent passwd "$USER" | cut -d: -f7. If it's fish, include --fish.

# start long-lived processes in the background
zmx run abc123-api -d vp dev --port 3000
zmx run abc123-worker -d deno run --allow-all worker.ts
# list them
zmx list --short
# check outputs as needed
zmx history abc123-api | tail -50
zmx history abc123-worker | tail -50

# or fire a command in the background whose exit status and output doesn't matter
zmx run abc123-fmt -d gofumpt -w

Interrupt a detached command

Send Ctrl+C if it's hanging or needs interruption:

zmx run abc123-dev-server $(printf '\x03')

Then check the history to see what went wrong:

zmx history abc123-dev-server | tail -50

Write files into a session

Useful for writing config or scripts into a remote session over SSH:

cat local.conf | zmx write abc123-dev-server /etc/app/app.conf