XTerm + Tmux Control

This skill enables control of graphical terminal windows through tmux, allowing you to run interactive programs and capture their output without direct TTY access.

Starting an XTerm with Tmux Session

# Start xterm with a new tmux session (runs in background)
xterm -e "tmux new-session -s SESSION_NAME" &

Replace SESSION_NAME with a descriptive name (e.g., gacia-test, app-debug).

Checking Tmux Sessions

# List all tmux sessions
tmux list-sessions

Sending Commands to Tmux Session

# Send a command and press Enter
tmux send-keys -t SESSION_NAME "your command here" Enter

# Send Ctrl+C to interrupt
tmux send-keys -t SESSION_NAME C-c

# Send other control sequences
tmux send-keys -t SESSION_NAME C-d  # Ctrl+D (EOF)
tmux send-keys -t SESSION_NAME C-z  # Ctrl+Z (suspend)

⚠️ Critical Gotcha: Never use newlines to chain commands

tmux send-keys accepts variadic key arguments — every token after the target is a key/string to send. When the Claude Code Bash tool collapses literal newlines, any commands you wrote on the next line get folded into the same shell line and become extra key arguments to send-keys. Those trailing tokens end up typed into the remote session (with spaces dropped, because each token is sent as one keystroke), producing garbled text like sleep3tmuxcapture-pane-tzellij-remote-p at the remote prompt.

❌ WRONG — newlines get collapsed; trailing words become send-keys args:

tmux send-keys -t SESSION_NAME "ssh host" Enter
sleep 3
tmux capture-pane -t SESSION_NAME -p

After newline-collapse this becomes one line: tmux send-keys -t SESSION_NAME "ssh host" Enter sleep 3 tmux capture-pane ... — so sleep, 3, tmux, capture-pane, … are typed into the tmux session as a single concatenated keystroke stream.

✅ RIGHT — chain commands with ; or &&:

tmux send-keys -t SESSION_NAME "ssh host" Enter ; sleep 3 ; tmux capture-pane -t SESSION_NAME -p

Or quote and chain inside one statement so each tool call invokes one logical sequence. This rule applies anywhere you call send-keys from the Bash tool, not only with Enter — any unquoted token after a send-keys argument list will be consumed as a key.

If you need a literal Space sent between separately-quoted send-keys strings, pass Space as an explicit key (e.g. send-keys "foo" Space "bar"), otherwise adjacent string args concatenate without a separator.

Capturing Screen Output

# Capture current pane contents
tmux capture-pane -t SESSION_NAME -p

# Capture with line numbers (useful for debugging)
tmux capture-pane -t SESSION_NAME -p -J

# Capture only last N lines
tmux capture-pane -t SESSION_NAME -p | tail -20

Rapid Snapshots (for TUI Debugging)

When debugging TUI applications or capturing startup sequences, take multiple snapshots in rapid succession:

# Take 20 snapshots at 0.1 second intervals
for i in $(seq 1 20); do
  echo "=== SNAPSHOT $i ($(date +%H:%M:%S.%3N)) ==="
  tmux capture-pane -t SESSION_NAME -p
  echo ""
  sleep 0.1
done

Adjust the count and sleep interval as needed:

• 0.05 for very fast transitions
• 0.1 for normal startup sequences
• 0.5 for slower state changes

Running Commands via nix-shell

If the target application requires nix-shell:

# Run command inside nix-shell
tmux send-keys -t SESSION_NAME "nix-shell --run 'your-command'" Enter

Complete Workflow Example

The snippets below are written as a shell script (newlines OK). When invoking from the Claude Code Bash tool, chain each step with ; so that no trailing tokens become extra send-keys arguments — see the Gotcha section above.

# 1. Start xterm with tmux
xterm -e "tmux new-session -s myapp" &

# 2. Wait for tmux to initialize
sleep 1

# 3. Verify session exists
tmux list-sessions

# 4. Run application
tmux send-keys -t myapp "nix-shell --run 'just run'" Enter

# 5. Capture rapid snapshots during startup
for i in $(seq 1 20); do
  echo "=== SNAPSHOT $i ==="
  tmux capture-pane -t myapp -p
  sleep 0.1
done

# 6. Stop application
tmux send-keys -t myapp C-c

# 7. Check final state
tmux capture-pane -t myapp -p | tail -30

# 8. Kill session when done
tmux kill-session -t myapp

Bash-tool-safe equivalent of steps 4–7 in a single call:

tmux send-keys -t myapp "nix-shell --run 'just run'" Enter ; sleep 2 ; tmux capture-pane -t myapp -p | tail -30 ; tmux send-keys -t myapp C-c

Troubleshooting

"session not found" error: The xterm/tmux may not have started yet. Add sleep 1 after starting xterm.

Empty capture output: The pane may not have rendered yet. Try capturing after a short delay.

Command not in PATH: The tmux session runs in a fresh shell. Use nix-shell --run or source appropriate environment files.

Capturing TUI panels: TUI frameworks like Rich use ANSI escape codes. The captured text will show the rendered layout with box-drawing characters.