repos / zmx

commit

1aaf713

parent

3477fb2

author

Eric Bower

date

2026-03-31 09:23:00 -0400 EDT

docs(ai): introduce claude skill

 1@@ -0,0 +1,74 @@
 2+---
 3+name: zmx-session
 4+description: This skill provides instructions for collaborative terminal debugging using zmx for session persistence. Use when the user wants to share a terminal session, debug server logs, troubleshoot infrastructure, or work together on a remote host via SSH. Triggers on mentions of "zmx", "shared session", "terminal debugging", or when user wants Claude to see terminal output.
 5+---
 6+
 7+# zmx Collaborative Terminal Sessions
 8+
 9+## Overview
10+
11+zmx is a lightweight terminal session persistence tool. It allows detaching from and reattaching to running shell sessions without killing processes. Unlike tmux, it focuses only on session persistence -- no windows, panes, or splits.
12+
13+This skill covers using zmx for collaborative debugging where Claude can directly view session history and execute commands.
14+
15+Run `zmx help` to understand the commands and when to run them.
16+
17+## Session Setup
18+
19+The user starts a zmx session and works within it:
20+
21+```bash
22+# Create or attach to a named session
23+zmx attach <session-name>
24+```
25+
26+Naming convention suggestion: use descriptive names like `debug-prod`, `k8s-issue`, `logs-api`.
27+
28+## Viewing Session Context
29+
30+Claude can directly view the terminal history without user intervention:
31+
32+```bash
33+# List active sessions
34+zmx list
35+
36+# View recent scrollback from a session (always pipe to tail to limit context)
37+zmx history <session-name> | tail -200
38+```
39+
40+These are read-only commands—run them freely to understand what's happening.
41+
42+If `zmx list` shows no sessions or the expected session is missing, inform the user and ask them to start or verify their zmx session.
43+
44+## Command Execution Protocol
45+
46+**Always ask permission before running commands that execute in the user's session.**
47+
48+To execute a command in a running session without attaching:
49+
50+```bash
51+zmx run <session-name> <command>
52+```
53+
54+Then you can wait for the task to complete by running:
55+
56+```bash
57+zmx wait <session-name>
58+```
59+
60+And you can track the exit code by running:
61+
62+```bash
63+zmx list | grep <session-name>
64+```
65+
66+Example workflow:
67+
68+1. User tells Claude the session name and describes the issue
69+1. Claude runs `zmx history <session-name> | tail -200` to see context
70+1. Claude analyzes and proposes a command
71+1. User approves
72+1. Claude runs via `zmx run <session-name> <command>`
73+1. Claude runs `zmx history <session-name> | tail -50` to see the output (zmx run does not return output directly -- it goes to the session's scrollback)
74+1. Claude evaluates the output and provides analysis
75+1. Repeat steps 3-7 as needed until the issue is resolved