/tmux

name: tmux
description: 'Read and drive other tmux panes when Claude runs inside tmux. Use whenever the user points at something running in another pane/split/window — their dev server, test watcher, build, logs, REPL, or another shell — e.g. "errors in my dev server", "read/tail my other pane", "is my server up and on what port", "run this in my other split", "restart the watcher". Also for driving interactive/long-running CLIs (Node REPL, vite/next dev, vitest, node inspect) and spawning isolated background tmux sessions.'
license: Vibecoded

tmux Skill

Use tmux as a programmable terminal multiplexer — both to **drive the panes the user is already watching** (their dev server, test watcher, REPL, logs) and to **run your own isolated sessions**. Works on Linux and macOS with stock tmux.

If you were launched from inside tmux, a `SessionStart` hook will already have told you so and listed the visible panes — which means Mode A below is available. When in doubt, prefer acting on the surfaces the user can actually see; that's usually what they mean.

Mode A — observe & control the user's tmux

This is the high-value mode when you're running inside the user's tmux: you can read and drive the same panes they're looking at, instead of spinning up a sandbox they can't see.

Confirm you're inside their tmux and find the server (`$TMUX` is `socket,pid,session`; the socket is the first field):

[ -n "$TMUX" ] && echo "in tmux — socket=${TMUX%%,*} pane=$TMUX_PANE"

Plain `tmux ...` already targets that server; `tmux -S "${TMUX%%,*}" ...` is the explicit form. The user usually works one window per project, so the panes sharing your window are the relevant ones. The bundled scripts cover the common operations — prefer them over hand-rolling:

./scripts/find-panes.sh -p                    # panes in YOUR window + listening ports
./scripts/find-panes.sh --session -p          # widen to the whole session

**Never assume `:0.0`.** The user's tmux may set `base-index 1` / `pane-base-index 1`, so targets can be 1-based. Always use the exact `session:win.pane` reported by `find-panes.sh` (or the SessionStart hook, or `$TMUX_PANE` for your own pane).

Read a pane's output — safe, do it freely:

tmux capture-pane -p -J -t projects:1.2 -S -200   # scrape a dev server's recent log

Run a one-off in the user's shell pane and get just its output back (waits for completion, prompt-agnostic, exits with the command's code):

./scripts/run-in-pane.sh -t projects:1.3 -- pnpm vitest run src/auth

Send keystrokes into a pane through the guard, which refuses editors/pagers (**read the safety rules below first**):

./scripts/safe-send.sh -t projects:1.2 --enter -- 'rs'   # type 'rs' + Enter (e.g. nodemon restart)
./scripts/safe-send.sh -t projects:1.2 --keys  -- C-c    # control keys

Writing into the user's panes

Reading with `capture-pane` never disturbs anything — reach for it first and often. `send-keys` is different: the keystrokes land in whatever currently has focus in that pane, so a careless send can corrupt the user's editor or kill a process they care about. Before any `send-keys` into a pane you didn't create:

• **Check what's running first** (the `[command]` from the list above). Don't send keystrokes into an editor (`nvim`, `vim`, `emacs`), a pager (`less`, `man`), or any stateful interactive program unless the user explicitly asked you to drive it.
• **Prefer your own surface for new work.** To run something long-lived, open a window the user can watch rather than hijacking a pane: `tmux new-window -n claude-task` (or a fresh session), then drive that. They still see it; you don't clobber their work.
• **Send deliberately.** Use `-l` for literal text; send control keys (`C-c`, `Enter`) as separate calls. Then `capture-pane` to confirm the effect before moving on.
• **Say what you touched.** Tell the user which pane you sent to and give them a `capture-pane`/`attach` command to verify.
• **Confirm destructive sends.** Interrupting a server they're running, or sending input that changes state, deserves a heads-up first unless they've already told you to go ahead.

`safe-send.sh` enforces the editor/pager check for you, and `run-in-pane.sh` is the safe way to run a one-off in a shell pane and capture its output — prefer them over raw `send-keys`.

---

The rest of this skill is **Mode B** — spinning up your own isolated sessions on a private socket, kept cleanly separate from the user's tmux. Use it for throwaway processes the user doesn't need to watch.

Quickstart (isolated socket)

SOCKET_DIR=${TMPDIR:-/tmp}/claude-tmux-sockets  # well-known dir for all agent sockets
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/claude.sock"                # keep agent sessions separate from your personal tmux
SESSION=claude-node                             # slug-like names; avoid spaces
tmux -S "$SOCKET" -f /dev/null new -d -s "$SESSION" -n shell  # -f /dev/null = stock config, so :0.0 indexing is predictable
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'node' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200  # watch output
tmux -S "$SOCKET" kill-session -t "$SESSION"                   # clean up

After starting a session ALWAYS tell the user how to monitor the session by giving them a command to copy paste:

To monitor this session yourself:
  tmux -S "$SOCKET" attach -t claude-node

Or to capture the output once:
  tmux -S "$SOCKET" capture-pane -p -J -t claude-node:0.0 -S -200

This must ALWAYS be printed right after a session was started and once again at the end of the tool loop. But the earlier you send it, the happier the user will be.

Socket convention

• Agents MUST place tmux sockets under `CLAUDE_TMUX_SOCKET_DIR` (defaults to `${TMPDIR:-/tmp}/claude-tmux-sockets`) and use `tmux -S "$SOCKET"` so we can enumerate/clean them. Create the dir first: `mkdir -p "$CLAUDE_TMUX_SOCKET_DIR"`.
• D