using-tmux

Original source / Raw SKILL.md

---
name: using-tmux
description: Control interactive CLI tools that require a real terminal via tmux send-keys. Use for git rebase -i, git add -p, vim, nano, Python/Node REPLs, or any command that hangs waiting for terminal input.
---

# Using tmux for Interactive Commands

**Persona:** Terminal automation expert - enables programmatic control of interactive applications.

## When NOT to Use

- Simple non-interactive commands (use Bash directly)
- Commands that accept stdin redirection
- One-shot commands that exit immediately

## Quick Reference

| Task | Command |
|------|---------|
| Start session | `tmux new-session -d -s NAME COMMAND` |
| Send input | `tmux send-keys -t NAME 'text' Enter` |
| Capture output | `tmux capture-pane -t NAME -p` |
| Kill session | `tmux kill-session -t NAME` |
| List sessions | `tmux list-sessions` |

## Core Pattern

```bash
# 1. Create detached session
tmux new-session -d -s mysession vim file.txt

# 2. Wait for init
sleep 0.3

# 3. Send keys (Enter, Escape are tmux key names, not \n)
tmux send-keys -t mysession 'iHello World' Escape ':wq' Enter

# 4. Capture output
tmux capture-pane -t mysession -p

# 5. Clean up
tmux kill-session -t mysession
```

## Special Keys

| Key | tmux Name |
|-----|-----------|
| Return | `Enter` |
| Escape | `Escape` |
| Ctrl+C | `C-c` |
| Ctrl+X | `C-x` |
| Arrows | `Up`, `Down`, `Left`, `Right` |
| Space | `Space` |
| Backspace | `BSpace` |

## Common Patterns

### Interactive Git Rebase
```bash
tmux new-session -d -s rebase -c /path/to/repo git rebase -i HEAD~3
sleep 0.5
tmux capture-pane -t rebase -p  # See editor
tmux send-keys -t rebase 'cwsquash' Escape 'j' 'cwsquash' Escape ':wq' Enter
tmux capture-pane -t rebase -p  # See result
tmux kill-session -t rebase
```

### Git Add Patch Mode
```bash
tmux new-session -d -s patch -c /path/to/repo git add -p
sleep 0.3
tmux capture-pane -t patch -p  # See hunk
tmux send-keys -t patch 'y'    # Stage this hunk
tmux capture-pane -t patch -p  # See next
tmux send-keys -t patch 'n'    # Skip this one
tmux send-keys -t patch 'q'    # Quit
tmux kill-session -t patch
```

### Python REPL
```bash
tmux new-session -d -s py python3
sleep 0.2
tmux send-keys -t py 'import math' Enter
tmux send-keys -t py 'print(math.pi)' Enter
tmux capture-pane -t py -p
tmux send-keys -t py 'exit()' Enter
tmux kill-session -t py
```

### Vim Edit
```bash
tmux new-session -d -s vim vim /tmp/test.txt
sleep 0.3
tmux send-keys -t vim 'i' 'New content here' Escape ':wq' Enter
tmux kill-session -t vim 2>/dev/null
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Blank output after new-session | Add `sleep 0.3` before capture |
| Commands typed but not executed | Send `Enter` as separate argument |
| Using `\n` for newline | Use `Enter` (tmux key name) |
| Orphaned sessions | Always `kill-session` when done |

## Should NOT Attempt

- Using for non-interactive commands (wasteful overhead)
- Sending shell escape sequences (`\n`, `\t`) instead of tmux key names
- Forgetting cleanup (orphaned sessions accumulate)
- Capturing immediately without sleep (blank output)

## Failure Behavior

If tmux commands fail:
1. Check if tmux is installed: `which tmux`
2. Check if session exists: `tmux has-session -t NAME`
3. List all sessions: `tmux list-sessions`
4. Kill stuck session: `tmux kill-session -t NAME`

## Escalation

| Situation | Action |
|-----------|--------|
| tmux not installed | Ask user to install: `apt install tmux` |
| Complex multi-step interaction | Break into smaller send-keys + capture cycles |
| Need to see full scrollback | Use `tmux capture-pane -t NAME -p -S -1000` |

## Related Skills

- **multi-llm**: Uses tmux for LLM CLI delegation
- **git-workflow**: Interactive git commands (rebase -i, add -p)