Detailed changes
@@ -112,9 +112,10 @@ token count, plus overall metadata usage. I've used and tested them most with
- [using-silverbullet](skills/using-silverbullet/SKILL.md): Manages notes in
[SilverBullet] via the CLI and Space Lua. Covers searching, reading, writing,
and editing pages, plus journal and task workflows.
-- [working-with-tmux](skills/working-with-tmux/SKILL.md): Spawns and manages
- background processes via tmux. Creates windows, sends commands, and captures
- output without blocking the main session. Useful for servers and long tasks.
+- [working-with-zmx](skills/working-with-zmx/SKILL.md): Manages persistent
+ terminal sessions for background processes, dev servers, and long-running tasks.
+ Creates sessions, runs commands detached, checks output, and writes files into
+ sessions over SSH.
- [writing-git-tags](skills/writing-git-tags/SKILL.md): Generates git tag
annotations from commit history following Semantic Versioning and Conventional
Commits via [git-format].
@@ -359,9 +360,9 @@ Token breakdown:
Token breakdown:
Name: 8 tokens
Description: 98 tokens
- Body: 412 tokens (54 lines)
+ Body: 489 tokens (56 lines)
───────────────────────────────────────────────
- Total: 518 tokens
+ Total: 595 tokens
=== handling-customer-data ===
@@ -435,11 +436,11 @@ Token breakdown:
Token breakdown:
Name: 10 tokens
Description: 62 tokens
- Body: 1801 tokens (222 lines)
+ Body: 1981 tokens (238 lines)
References:
writing-plugins.md 1151 tokens
───────────────────────────────────────────────
- Total: 3024 tokens
+ Total: 3204 tokens
=== notifying-through-ntfy ===
@@ -534,23 +535,14 @@ Token breakdown:
───────────────────────────────────────────────
Total: 799 tokens
-=== using-silverbullet ===
+=== working-with-zmx ===
Token breakdown:
Name: 8 tokens
- Description: 45 tokens
- Body: 1001 tokens (118 lines)
- ───────────────────────────────────────────────
- Total: 1054 tokens
-
-=== working-with-tmux ===
-
-Token breakdown:
- Name: 8 tokens
- Description: 32 tokens
- Body: 916 tokens (129 lines)
+ Description: 58 tokens
+ Body: 564 tokens (71 lines)
───────────────────────────────────────────────
- Total: 956 tokens
+ Total: 630 tokens
=== writing-git-tags ===
@@ -591,10 +583,10 @@ Token breakdown:
SUMMARY
============================================================
-Skills: 32
-Metadata: 2002 tokens
-Combined bodies: 33991 tokens
-Overall: 89506 tokens
+Skills: 31
+Metadata: 1975 tokens
+Combined bodies: 32895 tokens
+Overall: 88383 tokens
Validation errors: 0
Largest skills (by total tokens):
@@ -1,136 +0,0 @@
----
-name: working-with-tmux
-description: Instructions for using tmux to spawn multiple processes, inspect them, and capture their output. Useful for running servers or long-running tasks in the background.
-metadata:
- source: https://github.com/ampcode/amp-contrib
----
-
-This skill lets you manage multiple concurrent processes (like servers, watchers, or long builds) using `tmux` directly from the `Bash` tool.
-
-You can spawn new windows or panes to handle these tasks without blocking your main communication channel.
-
-## 1. Verify Environment & Check Status
-
-First, verify you are running inside tmux:
-
-```bash
-echo $TMUX
-```
-
-If this returns empty, you are not running inside tmux. Use `echo "agent-$(openssl rand -hex 3)"` to generate a unique session ID, then create a new session with a window named after what you're working on. You may skip step 2.1, creating the new window within an existing session.
-
-Once verified, check your current windows:
-
-```bash
-tmux list-windows
-```
-
-## 2. Spawn a Background Process
-
-To run a command (e.g., a dev server) in a way that persists and can be inspected:
-
-1. **Create a new detached window** with a specific name. This keeps it isolated and easy to reference.
-
- ```bash
- tmux new-window -n "server-log" -d
- ```
-
- _(Replace "server-log" with a relevant name for your task)_
-
-2. **Send the command** to that window.
- ```bash
- tmux send-keys -t "server-log" "npm start" C-m
- ```
- _(`C-m` simulates the Enter key)_
-
-## 3. Inspect Output (Read Logs)
-
-You can read the output of that pane at any time without switching your context.
-
-Get the current visible screen:
-
-```bash
-tmux capture-pane -p -t "server-log"
-```
-
-Get the entire history (scrollback, can produce _excessive_ tokens):
-
-```bash
-tmux capture-pane -p -S - -t "server-log"
-```
-
-Prefer to pipe the full scrollback buffer through grep/sed/tac/etc. to view just the content between your last command and the next prompt (exclusive).
-
-### Filtering between prompts
-
-When running commands on a remote shell, use `sed` to extract output between the shell prompt boundaries:
-
-```bash
-tmux capture-pane -p -S - -t "ID" | sed -n '/PROMPT_PATTERN/,/PROMPT_PATTERN/{//d;p}'
-```
-
-When prompts are long or appear in scrollback noise, generate random anchors to delimit output cleanly:
-
-```bash
-A=$(openssl rand -hex 4)
-echo "A: $A"
-tmux send-keys -t "ID" "echo ${A}-st; YOUR_COMMAND; echo ${A}-end" C-m
-sleep 1
-tmux capture-pane -p -S - -t "ID" | sed -n '/^'"$A"'-st$/,/^'"$A"'-end$/{/^'"$A"'/d;p}'
-```
-
-The `-st`/`-end` suffixes prevent matching the anchor inside the echoed command line.
-
-When scrollback becomes too noisy, clear it:
-
-```bash
-tmux send-keys -t "ID" 'clear' C-m
-tmux clear-history -t "ID"
-```
-
-## 4. Interact with the Process
-
-If you need to stop or restart the process:
-
-**Send Ctrl+C (Interrupt):**
-
-```bash
-tmux send-keys -t "server-log" C-c
-```
-
-**Kill the window (Clean up):**
-
-```bash
-tmux kill-window -t "server-log"
-```
-
-## 5. Advanced: Chaining Commands
-
-You can chain multiple tmux commands in a single invocation using `';'` (note the quotes to avoid interpretation by the shell). This is faster and cleaner than running multiple `tmux` commands.
-
-Example: Create window and start process in one go:
-
-```bash
-tmux new-window -n "server-log" -d ';' send-keys -t "server-log" "npm start" C-m
-```
-
-## 6. Parallel Work
-
-Spin up multiple windows for independent tasks (downloads, research queries, builds):
-
-```bash
-for name in task-a task-b task-c; do tmux new-window -n "$name" -d; done
-```
-
-Send commands to each, then check results as they complete. Clean up finished windows:
-
-```bash
-tmux kill-window -t "task-a"
-```
-
-## Summary of Pattern
-
-0. `echo $TMUX`
-1. `tmux new-window -n "ID" -d`
-2. `tmux send-keys -t "ID" "CMD" C-m`
-3. `tmux capture-pane -p -t "ID"` (with anchor filtering for remote shells)
@@ -0,0 +1,83 @@
+---
+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
+```