repos / zmx

commit

a0ead2f

parent

984a184

author

Eric Bower

date

2025-11-26 21:36:03 -0500 EST

docs: readme

 1@@ -18,10 +18,16 @@ session persistence for terminal processes
 2 
 3 ## usage
 4 
 5-- `zmx attach {session_name} [command...]` - create or attach to a session, optionally running a command instead of shell
 6-- `zmx detach [{session_name}]` (or Ctrl+\\) - detach all connected clients to session, can be used inside session without providing name
 7-- `zmx list` - list sessions
 8-- `zmx kill {session_name}` kill pty and all clients attached to session
 9+```
10+Usage: zmx <command> [args]
11+
12+Commands:
13+  attach <name> [command...]  Create or attach to a session
14+  detach                      Detach from current session (or ctrl+\)
15+  list                        List active sessions
16+  kill <name>                 Kill a session and all attached clients
17+  help                        Show this help message
18+```
19 
20 ### examples
21 
22@@ -32,10 +38,8 @@ zmx attach build make -j8   # run a build, reattach to check progress
23 zmx attach mux dvtm         # run a multiplexer inside zmx
24 ```
25 
26-## todo
27-
28-- [ ] Integrate with `libghostty` to restore terminal state on re-attach
29-- [ ] Binary distribution (e.g. pkg managers)
30+> [!IMPORTANT]
31+> Press `ctrl+\` to detach from the session.
32 
33 ## shell prompt
34 
35@@ -56,6 +60,40 @@ function fish_prompt --description 'Write out the prompt'
36 end
37 ```
38 
39+### bash
40+
41+todo.
42+
43+### zsh
44+
45+todo.
46+
47+## socket file location
48+
49+Each session gets its own unix socket file.  Right now, the default location is `/tmp/zmx`.  At the moment this is not configurable.
50+
51+## debugging
52+
53+We store global logs for cli commands in `/tmp/zmx/logs/zmx.log`.  We store session-specific logs in `/tmp/zmx/logs/{session_name}.log`.  These logs rotate to `.old` after 5MB.  At the moment this is not configurable.
54+
55+## a note on configuration
56+
57+At this point, nothing is configurable and we aren't convinced they should ever be configurable.  Configuration adds complexity and it forces maintainers to support users changing the default behavior.  This is a burden.  For example, if we allow changing the detach key shortcut then we need to debug all the different incantations people come up with which can be very tricky in a terminal environment.  We have figured out how to support `ctrl+\` because we think this is a great option.  Tread lightly when submitting PRs to add configuration to this tool.  Having said that, we will always entertain configuration ideas.
58+
59+## a smol contract
60+
61+- Write programs that do one thing and do it well.
62+- Write programs that behave the way most users expect them to behave.
63+- Write programs that a single person can maintain.
64+- Write programs that compose with other smol tools.
65+- Write programs that can be finished.
66+
67+## todo
68+
69+- QA
70+- Integrate with `libghostty` to restore terminal state on re-attach
71+- Binary distribution (e.g. pkg managers)
72+
73 ## prior art
74 
75 Below is a list of projects that inspired me to build this project.