home / skills / vaayne / agent-kit / tmux

tmux skill

safe

This skill helps you manage interactive terminal sessions with tmux, enabling persistent REPLs and parallel CLI agents for complex workflows.

npx playbooks add skill vaayne/agent-kit --skill tmux

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.2 KB

---
name: tmux
description: Control interactive terminal sessions via tmux. Use when tasks need persistent REPLs, parallel CLI agents, or any process requiring a TTY that simple shell execution cannot handle.
metadata:
  os:
    - darwin
    - linux
  requires:
    bins:
      - tmux
---

# tmux Skill

Use tmux only when you need an interactive TTY. Prefer exec background mode for long-running, non-interactive tasks.

## Quickstart

```bash
SOCKET_DIR="${TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/tmux.sock"
SESSION=my-session

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
```

## Essential Commands

| Action            | Command                                                  |
| ----------------- | -------------------------------------------------------- |
| Send text         | `tmux -S "$SOCKET" send-keys -t target -l -- "$cmd"`     |
| Send Enter/Ctrl-C | `tmux -S "$SOCKET" send-keys -t target Enter` / `C-c`    |
| Capture output    | `tmux -S "$SOCKET" capture-pane -p -J -t target -S -200` |
| List sessions     | `tmux -S "$SOCKET" list-sessions`                        |
| Kill session      | `tmux -S "$SOCKET" kill-session -t "$SESSION"`           |
| Kill server       | `tmux -S "$SOCKET" kill-server`                          |

## Conventions

- **Socket**: `TMUX_SOCKET_DIR` env var (default `${TMPDIR:-/tmp}/tmux-sockets`)
- **Target format**: `session:window.pane` (defaults to `:0.0`)
- **Python REPLs**: Set `PYTHON_BASIC_REPL=1` to avoid readline issues

## Helper Scripts

```bash
./scripts/find-sessions.sh -S "$SOCKET"        # list sessions
./scripts/find-sessions.sh --all               # scan all sockets
./scripts/wait-for-text.sh -t sess:0.0 -p 'pattern' [-T 20] [-i 0.5]
```

## Parallel Agents Example

```bash
SOCKET="${TMPDIR:-/tmp}/agents.sock"
for i in 1 2 3; do tmux -S "$SOCKET" new-session -d -s "agent-$i"; done
tmux -S "$SOCKET" send-keys -t agent-1 "codex --yolo 'Fix bug'" Enter

# Poll for completion
tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -3 | grep -q "❯" && echo "Done"
```

Overview

This skill provides a focused tmux integration to control interactive terminal sessions for AI coding agents. It is designed for use when tasks require persistent TTYs, parallel REPLs, or any interactive process that simple shell execution cannot manage. Use it to create, script, and inspect tmux sessions programmatically from TypeScript-driven agents.

How this skill works

The skill wraps tmux socket-based commands to create detached sessions, send keystrokes, capture pane output, and manage the tmux server lifecycle. It uses a configurable socket directory and the session:window.pane target format to address panes precisely. Helpers include scripts to list sessions, wait for text patterns, and run multiple agent sessions in parallel.

When to use it

Running persistent REPLs (Python, node, etc.) that need a TTY and interactive input.
Orchestrating multiple parallel CLI agents that must run concurrently and be inspected.
Interacting with tools that rely on line discipline or terminal features (curses, readline).
Capturing terminal output or logs from an interactive process for parsing or assertions.
Launching quick, interactive experiments where attaching/detaching a session is useful.

Best practices

Prefer exec/background mode for long-running non-interactive tasks; use tmux only for TTY-required workflows.
Use a dedicated socket directory (TMUX_SOCKET_DIR) per environment to avoid cross-process collisions.
Address panes using session:window.pane to target commands deterministically.
Send commands with send-keys and terminate input with Enter; use capture-pane to read output safely.
Set PYTHON_BASIC_REPL=1 when running Python REPLs to avoid readline issues inside tmux.

Example use cases

Start a detached tmux session running a Python REPL, send code snippets, and capture results for analysis.
Spawn multiple agent sessions (agent-1, agent-2, agent-3) to run concurrent code generation tasks and poll panes for completion markers.
Run an interactive test harness that requires a tty-based UI, capture panes, and assert expected prompts or outputs.
Maintain a persistent debugging REPL across restarts so agents can attach, inspect state, and continue a session.

FAQ

How do I target a specific pane?

Use the session:window.pane format (for example my-session:0.1). If omitted, tmux defaults to :0.0.

When should I not use tmux?

Avoid tmux for long-running non-interactive jobs; prefer running processes directly or via background exec to reduce overhead and complexity.