repos / zmx

commit

9d6ede4

parent

8f9ed48

author

Eric Bower

date

2025-11-29 08:31:49 -0500 EST

docs: readme

 1@@ -2,6 +2,8 @@
 2 
 3 session persistence for terminal processes
 4 
 5+Reason for this tool: [You might not need `tmux`](https://bower.sh/you-might-not-need-tmux)
 6+
 7 ## features
 8 
 9 - Persist terminal shell sessions (pty processes)
10@@ -71,6 +73,61 @@ todo.
11 
12 todo.
13 
14+## philosophy
15+
16+The entire argument for `zmx` instead of something like `tmux` that has windows, panes, splits, etc. is that job should be handled by your os window manager.  By using something like `tmux` you now have redundent functionality in your dev stack: a tiling manager for your os windows and a tiling manager for your terminal windows.
17+
18+Instead, we focus this tool specifically on session persistence and defer window management to your os wm.
19+
20+## ssh workflow
21+
22+Using `zmx` with `ssh` is a first-class citizen.  Instead of sshing into your remote system with a single terminal and have `n` tmux pandes, you open `n` number of terminals open and ssh into your remote system `n` number of times.  This might sound like a downgrade, but there are tools to make this a delightful workflow.
23+
24+First, create an ssh config entry for your remote dev server:
25+
26+```bash
27+Host = d.*
28+    HostName 192.168.1.xxx
29+
30+    RemoteCommand zmx attach %k
31+    RequestTTY yes
32+    ControlPath ~/.ssh/cm-%r@%h:%p
33+    ControlMaster auto
34+    ControlPersist 10m
35+```
36+
37+Now you can spawn as many terminal sessions as you'd like:
38+
39+```bash
40+ssh d.term
41+ssh d.irc
42+ssh d.pico
43+ssh d.dotfiles
44+```
45+
46+This will create or attach to each session and since we are using `ControlMaster` the same `ssh` connection is reused for near-instant connection times.
47+
48+Now you can use the [`autossh`](https://linux.die.net/man/1/autossh) tool to make your ssh connections auto-reconnect.  For example, if you have a laptop and close/open your laptop lid it will automatically reconnect all your ssh connections:
49+
50+```bash
51+autossh -M 0 d.term
52+```
53+
54+Or create an `alias`/`abbr`:
55+
56+```fish
57+abbr -a ash "autossh -M 0"
58+```
59+
60+```bash
61+ash d.term
62+ash d.irc
63+ash d.pico
64+ash d.dotifles
65+```
66+
67+Wow!  Now you can setup all your os tiling windows how you like them for your project and have as many windows as you'd like, almost replicating exactly what `tmux` used to do with a slightly different workflow.
68+
69 ## socket file location
70 
71 Each session gets its own unix socket file. Right now, the default location is `/tmp/zmx`. At the moment this is not configurable.