---
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:

```bash
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:

```bash
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`.

```bash
# 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:

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

Then check the history to see what went wrong:

```bash
zmx history abc123-dev-server | tail -50
```

## Write files into a session

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

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