docs: note that nested sessions are not supported (#242)

Commit `a959c5a`

Ngo Quoc Viet · 2026-08-17 14:45:19 -0400 EDT

parent cd88d1b

docs: note that nested sessions are not supported (#242)

attach reads ZMX_SESSION and switches the calling terminal, which surprises
callers that inherited the variable rather than choosing it. Document the
env -u workaround and point non-interactive callers at run.

Refs #151, #200

1 files changed, +19, -0

M README.md

+19, -0

......@@ -121,6 +121,25 @@ Commands:
  [h]elp                                   Show this help
```

## nested sessions

Nested sessions are not supported. Inside a session `ZMX_SESSION` is set, and
`attach` reads it: instead of creating another client it switches the calling
terminal to the session you named.

That matters when the variable is inherited rather than chosen. A script, build
tool, or coding agent started inside a session runs with `ZMX_SESSION` set, so
`zmx attach other` from there moves the terminal somebody was using, and the
session it was showing is left with no client.

Unset it in anything that attaches on its own behalf:

```bash
env -u ZMX_SESSION zmx attach other
```

For non-interactive work prefer `zmx run`, which never switches the caller.

## shell prompt

When you attach to a `zmx` session, we don't provide any indication that you are inside `zmx`. We do provide an environment variable `ZMX_SESSION` which contains the session name.

...	...		@@ -121,6 +121,25 @@ Commands:
121	121		[h]elp Show this help
122	122		```
123	123
	124	+	## nested sessions
	125	+
	126	+	Nested sessions are not supported. Inside a session `ZMX_SESSION` is set, and
	127	+	`attach` reads it: instead of creating another client it switches the calling
	128	+	terminal to the session you named.
	129	+
	130	+	That matters when the variable is inherited rather than chosen. A script, build
	131	+	tool, or coding agent started inside a session runs with `ZMX_SESSION` set, so
	132	+	`zmx attach other` from there moves the terminal somebody was using, and the
	133	+	session it was showing is left with no client.
	134	+
	135	+	Unset it in anything that attaches on its own behalf:
	136	+
	137	+	```bash
	138	+	env -u ZMX_SESSION zmx attach other
	139	+	```
	140	+
	141	+	For non-interactive work prefer `zmx run`, which never switches the caller.
	142	+
124	143		## shell prompt
125	144
126	145		When you attach to a `zmx` session, we don't provide any indication that you are inside `zmx`. We do provide an environment variable `ZMX_SESSION` which contains the session name.

Commit a959c5a

Commit `a959c5a`