Using Tmux Ssh

---
name: using-tmux-ssh
description:
  "Use when about to ssh to a host, run a command on a VM or remote box, start a
  long test or build on another machine, inspect a remote log, or recover after
  an ssh connection dropped or a remote command timed out. Use tmux-ssh for
  remote commands, saved-watch resume, and concurrent observation."
---

## Running Remote Commands With tmux-ssh

`tmux-ssh` drives one persistent SSH login per host in a local tmux pane. Use it
for every command on another machine or VM, short or long, including remote
tests, builds, and log reads. Use `--read` and `--status` to observe; never use
plain SSH polling or Monitor loops.

### Resolve the bundled executable

Resolve `resources/tmux-ssh` relative to the active `using-tmux-ssh` skill
folder supplied by your runtime. Set `TMUX_SSH` to that absolute executable
path, then read its live help:

```bash
TMUX_SSH='/absolute/path/to/using-tmux-ssh/resources/tmux-ssh'
"$TMUX_SSH" --help
```

The runtime's loaded plugin root contains
`skills/using-tmux-ssh/resources/tmux-ssh` for Claude, Codex, Cursor, and Muse;
OpenCode contains `assets/skills/using-tmux-ssh/resources/tmux-ssh`. Locate the
root from the active skill's path rather than assuming plugin root environment
variables are set in an interactive shell. Nothing else from Thrum is required;
local `tmux` and `ssh` must be installed.

### Usage

The examples below invoke the resolved executable through `"$TMUX_SSH"`. `HOST`
is an SSH config alias or `user@host`.

```bash
"$TMUX_SSH" HOST                                  # connect if needed; print status
"$TMUX_SSH" HOST 'uname -a'                        # finite command; return its exit code
"$TMUX_SSH" HOST --timeout 900 'make test'          # bounded observation, in seconds
"$TMUX_SSH" HOST --resume --timeout 900            # continue the saved watch; never resend
"$TMUX_SSH" HOST --status                          # session and recorded state
"$TMUX_SSH" HOST --read --settle                    # screen; usable during another call
"$TMUX_SSH" HOST --abort                           # deliberately interrupt and clear the watch
"$TMUX_SSH" HOST --kill                            # close SSH and clear saved state

"$TMUX_SSH" HOST --send 'top'                      # interactive program
"$TMUX_SSH" HOST --read
"$TMUX_SSH" HOST --send --key C-c

"$TMUX_SSH" HOST "tmux new -d -s JOB 'long-command >job.log 2>&1'"
```

Run mode waits for a command that ends. For editors, REPLs, attached tmux, and
other programs that stay open, use `--send`/`--read`. Run mode refuses obvious
interactive commands with code 2; use `--force-run` only deliberately. `--send`
types into the current program and refuses a dead session rather than
reconnecting and losing interactive state.

Quote remote commands locally so variables expand on the intended machine. They
execute in the remote login shell, which may be zsh; invoke `bash` for Bash
syntax. For long or complex content, transfer a script using `scp` or `rsync`
with the same connection options, then run a short command through `tmux-ssh`.
The wrapper transports commands, not files.

### Rules

- **One command per host session.** Mutating calls share a local per-host lock
  and wait up to 30 seconds by default. `--read` and `--status` observe without
  that lock. Coordinate drivers across machines or different `TMUX_SSH_DIR`
  values; these do not provide a global lock.
- **One local tmux session per `TMUX_SSH_DIR`.** The session is named
  `ts_<host>_<8 hex of a hash of the canonical TMUX_SSH_DIR>` on tmux socket
  `tmux-ssh`, so drivers with different state dirs never share, reuse, or kill
  each other's session. The session records its dir in the tmux option
  `@tmux_ssh_dir` (tmux >= 2.9 is required for these options; older tmux is
  refused with a clear error before any session is touched). Every verb that
  touches a session (`--attach`, `--status`, `--read`, `--send`, `--resume`,
  run/ensure, `--kill`, `--abort`) refuses with exit 125 and changes nothing on
  a session recorded for another dir; the message names both dirs. A dir with no
  session of its own is never refused for clearing its own stale watch or input
  guard with `--kill`/`--abort`. A pre-upgrade session named plain `ts_<host>`
  is adopted only by a dir whose saved state names it; each adopter is recorded
  in `@tmux_ssh_dirs`, and if more than one dir has adopted it the session is
  ambiguous: `--kill`, `--abort` and the typing verbs refuse for all of them
  (`--status`, `--read`, `--attach` still work). Confirm which dir owns the
  running command, then kill that tmux session by hand
  (`tmux -L tmux-ssh kill-session -t =NAME`) or let the command end. The first
  adopter cannot see a sibling that has not yet touched the session. Run from
  the owning `TMUX_SSH_DIR`, or kill by hand as above.
- **Resume observation, never resubmit a queued or visible command.** Code 124
  ends the wait; the command may still be running or waiting for input. Use
  `--read`, then `--resume`, which retains the watch and never sends the command
  again. Resume reuses the original timeout unless overridden. Other run calls
  refuse while a watch remains.
- **Interrupt deliberately.** `--interrupt-on-timeout` sends Ctrl-C when the
  wait expires. `--abort` sends Ctrl-C and clears the watch; code 0 reports a
  ready/finished/gone session, code 1 means the shell did not answer. Inspect
  `--read` before further input. An abort receipt does not prove job success.
- **Give long jobs an independent remote lifecycle.** Use detached remote tmux,
  retaining the job name and logs. An ordinary call can reconnect a dead SSH
  session, but a drop during foreground execution leaves completion unknown and
  may terminate that command. Check the job and its results before deciding to
  retry. `--kill` closes SSH; it does not stop an independent remote job.
- **Interpret the diagnostic and completion evidence.** Remote command exit
  codes are passed through and can overlap wrapper codes. Wrapper code 124 is a
  wait timeout; 125 is refusal or 'completion unknown', so it alone cannot prove
  nothing ran; 2 is a usage error; 3 means input state UNKNOWN after a failed
  keystroke, dropped send, or failed watch persistence. Code 3 guards later
  typing until `--kill`; `--read`, `--status`, and `--resume` still work. Do not
  blindly retry unknown completion or input, or kill another driver's session or
  lock merely because it looks stuck.

### Connection options and pool leases

Obtain the key, known-hosts file, target address, and actual remote OS hostname
from the current lease. Keep these values outside the skill.

```bash
TMUX_SSH_OPTS='-i /path/to/lease-key -o IdentitiesOnly=yes -o UserKnownHostsFile=/path/to/lease-known-hosts -o StrictHostKeyChecking=yes' \
TMUX_SSH_EXPECT_HOST='<remote-os-hostname>' \
"$TMUX_SSH" user@<lease-address> 'uname -a'
```

Host-key checking: `tmux-ssh` adds `-o StrictHostKeyChecking=accept-new` only
when `TMUX_SSH_OPTS` names no `StrictHostKeyChecking` option and `ssh -G <host>`
reports SSH's built-in default (`ask`). A value you set in `TMUX_SSH_OPTS` or in
`~/.ssh/config` (`yes`, `no`, `accept-new`) always wins, so a host alias with
`StrictHostKeyChecking yes` stays strict. If the `ssh -G` probe fails or times
out, nothing is added and SSH's own default applies. The probe is killed after
`TMUX_SSH_PROBE_TIMEOUT` seconds (default 5; a non-integer or `0` means 5).
Residual: an explicit `StrictHostKeyChecking ask` in `~/.ssh/config` looks
identical to the built-in default in `ssh -G` output, so it also gets
`accept-new`; put `-o StrictHostKeyChecking=ask` in `TMUX_SSH_OPTS` to keep it.

Options precede built-in defaults, so SSH's first `-o` wins. Allowed characters
are letters, digits, spaces, and `- _ . / = : , @ ~ + %`; paths cannot contain
spaces. A live session retains its original options: deliberately close it with
`--kill` before changing them. `--help`, `--status`, and `--kill` work with
invalid options. `--expect-host` overrides `TMUX_SSH_EXPECT_HOST` and matches
short/FQDN hostname forms case-insensitively; the SSH alias need not match the
OS hostname.

### Execution identity checks

SSH is the pane's own process; a dropped connection leaves a dead pane, not a
local shell. Run mode checks a live SSH pane, probes the recorded hostname, and
wraps execution with a hostname check. Interactive input checks the live SSH
pane because a program may own stdin. These checks catch mistaken targets; they
are not an adversarial security boundary. Remote targets reporting the local
hostname are refused; explicit `localhost`/`127.0.0.1` aliases permit
intentional local use.