1---
 2name: working-with-zmx
 3description: >-
 4  Manages persistent terminal sessions for background processes, dev servers,
 5  and long-running tasks. Use when the user mentions running something in the
 6  background, starting a dev server, running commands over SSH in a persistent
 7  session, or needs an alternative to tmux/screen for session multiplexing.
 8license: GPL-3.0-or-later
 9metadata:
10  author: Amolith <amolith@secluded.site>
11---
12
13- `zmx attach <sess-name> [command...]`: Create a session and attach to it (interactive. likely never use this; it's for your human operator).
14- `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.
15- `zmx list [--short]`: prefer `--short`
16- `zmx kill <sess-name>... [--force]`
17- `zmx detach <sess-name>`: detach all clients from a session.
18- `zmx history <sess-name>`: print session history in plaintext
19  - `--vt` adds VT escape sequences and `--html` produces HTML. Prefer plaintext.
20- `zmx wait <sess-name>...`: Block until a detached run task completes.
21- `zmx tail <sess-name>...`: Follow session output in real time.
22- `zmx write <sess-name> <file_path>`: Write stdin to a file path inside the session (works over SSH).
23
24## Starting sessions
25
26Check for existing sessions to avoid duplicates with `zmx list --short`. Always use unique session IDs:
27
28```bash
29openssl rand -hex 3 # in one tool call
30## abc123
31# in subsequent tool calls
32zmx run "abc123-dev" -d deno run --allow-all server.ts
33zmx history "abc123-dev" | tail -50
34```
35
36## Running commands in the foreground
37
38The simplest situation:
39
40```bash
41zmx run abc123-dev go build ./...
42# ... output ...
43```
44
45## Detaching
46
47First check the user's shell with `getent passwd "$USER" | cut -d: -f7`. If it's fish, include `--fish`.
48
49```bash
50# start long-lived processes in the background
51zmx run abc123-api -d vp dev --port 3000
52zmx run abc123-worker -d deno run --allow-all worker.ts
53# list them
54zmx list --short
55# check outputs as needed
56zmx history abc123-api | tail -50
57zmx history abc123-worker | tail -50
58
59# or fire a command in the background whose exit status and output doesn't matter
60zmx run abc123-fmt -d gofumpt -w
61```
62
63## Interrupt a detached command
64
65Send Ctrl+C if it's hanging or needs interruption:
66
67```bash
68zmx run abc123-dev-server $(printf '\x03')
69```
70
71Then check the history to see what went wrong:
72
73```bash
74zmx history abc123-dev-server | tail -50
75```
76
77## Write files into a session
78
79Useful for writing config or scripts into a remote session over SSH:
80
81```bash
82cat local.conf | zmx write abc123-dev-server /etc/app/app.conf
83```