using-tmux

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.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill enables the automation of interactive command-line interface (CLI) tools using tmux. It allows AI agents to programmatically control applications that typically require manual terminal input—such as Vim, interactive Git commands, and language REPLs—by sending simulated keystrokes and capturing terminal output in detached sessions.

Use Cases

  • Automated Git Workflows: Executing complex interactive operations like 'git rebase -i' or 'git add -p' programmatically without manual user intervention.
  • Programmatic File Editing: Using terminal-based editors like Vim or Nano to modify configuration files or source code within an automated agentic workflow.
  • Interactive REPL Management: Controlling Python, Node.js, or other language REPLs to execute code snippets and capture real-time results in a persistent session.
  • Terminal Automation for Legacy Tools: Managing any CLI tool that hangs or waits for terminal input, ensuring smooth execution of scripts that are not natively non-interactive.
nameusing-tmux
descriptionControl 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

# 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

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

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

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

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
  • multi-llm: Uses tmux for LLM CLI delegation
  • git-workflow: Interactive git commands (rebase -i, add -p)