$ ~/registry/skill/obra-using-tmux-for-interactive-commands

SKILL

using-tmux-for-interactive-commands

Name: using-tmux-for-interactive-commands
Author: obra

Run interactive CLI sessions safely via tmux for editors, REPLs, and Git flows.

Source

GitHub

Updated

2026-06-07

// securityLow risk

Prompt only, no code
Open source

Running security audit…

Credentials
Network egress
Code execution
Data access
Supply chain

// install

Copy the install command and let the AI configure it · recommended for beginners

Please install the "using-tmux-for-interactive-commands" skill from askskill:
1. Download https://raw.githubusercontent.com/obra/superpowers-lab/main/skills/using-tmux-for-interactive-commands/SKILL.md
2. Save it as ~/.claude/skills/using-tmux-for-interactive-commands/SKILL.md
3. Reload skills and tell me it's ready

// download

Download SKILL.mdInstall manifest ↗

// examples

Run interactive Git rebase in tmux

Prompt

Show me how to start a detached tmux session, run git rebase -i HEAD~5 inside it, and use send-keys to save and exit. Include complete commands and precautions.

Expected

A runnable set of tmux and Git commands to create the session, start interactive rebase, and control keypresses.

Control a Python REPL through tmux

Prompt

I need to launch a Python REPL in a detached tmux session, send several lines of Python code, and inspect the output. Give me the steps, including session creation, command sending, and result checking.

Expected

Instructions for running a Python REPL in tmux, injecting inputs, and capturing or viewing terminal output.

Edit a file with Vim in the background

Prompt

Demonstrate how to use tmux to open Vim in a detached session, then use send-keys to enter insert mode, add content, and save and quit.

Expected

A tmux control workflow for Vim covering launch, key sending, save-and-quit, and common risk notes.

// docs

Using tmux for Interactive Commands

Overview

Interactive CLI tools (vim, interactive git rebase, REPLs, etc.) cannot be controlled through standard bash because they require a real terminal. tmux provides detached sessions that can be controlled programmatically via send-keys and capture-pane.

When to Use

Use tmux when:

Running vim, nano, or other text editors programmatically
Controlling interactive REPLs (Python, Node, etc.)
Handling interactive git commands (git rebase -i, git add -p)
Working with full-screen terminal apps (htop, etc.)
Commands that require terminal control codes or readline

Don't use for:

Simple non-interactive commands (use regular Bash tool)
Commands that accept input via stdin redirection
One-shot commands that don't need interaction

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`
Stop session	`tmux kill-session -t <name>`
List sessions	`tmux list-sessions`

Core Pattern

Before (Won't Work)

# This hangs because vim expects interactive terminal
bash -c "vim file.txt"

After (Works)

# Create detached tmux session
tmux new-session -d -s edit_session vim file.txt

# Send commands (Enter, Escape are tmux key names)
tmux send-keys -t edit_session 'i' 'Hello World' Escape ':wq' Enter

# Capture what's on screen
tmux capture-pane -t edit_session -p

# Clean up
tmux kill-session -t edit_session

Implementation

Basic Workflow

Create detached session with the interactive command
Wait briefly for initialization (100-500ms depending on command)
Send input using send-keys (can send special keys like Enter, Escape)
Capture output using capture-pane -p to see current screen state
Repeat steps 3-4 as needed
Terminate session when done

Special Keys

Common tmux key names:

Enter - Return/newline
Escape - ESC key
C-c - Ctrl+C
C-x - Ctrl+X
Up, Down, Left, Right - Arrow keys
Space - Space bar
BSpace - Backspace

Working Directory

Specify working directory when creating session:

tmux new-session -d -s git_session -c /path/to/repo git rebase -i HEAD~3

Helper Wrapper

For easier use, see /home/jesse/git/interactive-command/tmux-wrapper.sh:

# Start session
/path/to/tmux-wrapper.sh start <session-name> <command> [args...]

# Send input
/path/to/tmux-wrapper.sh send <session-name> 'text' Enter

# Capture current state
/path/to/tmux-wrapper.sh capture <session-name>

# Stop
/path/to/tmux-wrapper.sh stop <session-name>

Common Patterns

Python REPL

tmux new-session -d -s python python3 -i
tmux send-keys -t python 'import math' Enter
tmux send-keys -t python 'print(math.pi)' Enter
tmux capture-pane -t python -p  # See output
tmux kill-session -t python

Vim Editing

tmux new-session -d -s vim vim /tmp/file.txt
sleep 0.3  # Wait for vim to start
tmux send-keys -t vim 'i' 'New content' Escape ':wq' Enter
# File is now saved

Interactive Git Rebase

tmux new-session -d -s rebase -c /repo/path git rebase -i HEAD~3
sleep 0.5
tmux capture-pane -t rebase -p  # See rebase editor
# Send commands to modify rebase instructions
tmux send-keys -t rebase 'Down' 'Home' 'squash' Escape
tmux send-keys -t rebase ':wq' Enter

Common Mistakes

Not Waiting After Session Start

Problem: Capturing immediately after new-session shows blank screen

Fix: Add brief sleep (100-500ms) before first capture

tmux new-session -d -s sess command
sleep 0.3  # Let command initialize
tmux capture-pane -t sess -p

Forgetting Enter Key

Problem: Commands typed but not executed

Fix: Explicitly send Enter

…

View full docs ↗

// from the same source

SKILL

Set conversation rules to discover and invoke skills before replying.

obraGet→

Let AI run commands in a shared tmux terminal with live human visibility.

—Get→

$ loading_