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