diff --git a/README.md b/README.md index 7a1a50738eebcc6afe6a49bf82bbe721cdfd5256..0b3f28504a81afb0afdc5a3b95c37cc3f3892faa 100644 --- a/README.md +++ b/README.md @@ -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): diff --git a/skills/working-with-tmux/SKILL.md b/skills/working-with-tmux/SKILL.md deleted file mode 100644 index c46ef0e834091921916204e9a8a57de81f9abdd4..0000000000000000000000000000000000000000 --- a/skills/working-with-tmux/SKILL.md +++ /dev/null @@ -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) diff --git a/skills/working-with-zmx/SKILL.md b/skills/working-with-zmx/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..afa76728b8fd4dd047e34526fb81e6c1f4d3efd5 --- /dev/null +++ b/skills/working-with-zmx/SKILL.md @@ -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 +--- + +- `zmx attach [command...]`: Create a session and attach to it (interactive. likely never use this; it's for your human operator). +- `zmx run [-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 ... [--force]` +- `zmx detach `: detach all clients from a session. +- `zmx history `: print session history in plaintext + - `--vt` adds VT escape sequences and `--html` produces HTML. Prefer plaintext. +- `zmx wait ...`: Block until a detached run task completes. +- `zmx tail ...`: Follow session output in real time. +- `zmx write `: 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 +```