| name | tmux |
| description | Terminal multiplexer management and workflow automation. Use this skill when working with tmux sessions, windows, and panes, managing terminal layouts, renaming windows intelligently based on project context, or automating terminal workflows with tmux commands. |
tmux Skill
Terminal multiplexer management with intelligent window naming and workflow automation.
Purpose
This skill provides comprehensive tmux management capabilities including:
- Session, window, and pane management
- Intelligent window renaming based on project context
- Terminal workflow automation
- MCP server integration for AI-driven tmux control
When to Use This Skill
Use this skill when:
- Managing tmux sessions, windows, or panes
- Renaming windows based on project or directory context
- Setting up development layouts with multiple panes
- Automating terminal workflows
- Integrating AI control with tmux via MCP
- Troubleshooting tmux configuration or layout issues
Core Concepts
Window Naming Strategy
Windows are automatically named based on these heuristics (in order of priority):
- Git Repository: If all panes in a window are in the same git repository, use the repository name
- Common Path: Use the common parent directory name shared by all panes
- Truncation: Names are truncated to 20 characters maximum for readability
- Duplicate Handling: Duplicate names get a suffix (-2, -3, etc.)
- Default Names Only: Only rename windows with default command-based names (bash, node, python, etc.)
- Respect Custom Names: Skip windows with user-assigned custom names
- Respect automatic-rename: Skip windows where automatic-rename is enabled
Standard Development Layout
When using tmux-dev-window, the standard pane layout is:
- Editor (top-left): Primary editor pane (named "editor")
- AI (top-right): AI assistant pane (named "ai")
- Shell (bottom): Command execution pane (named "shell")
Tools and Scripts
Window Management
tmux-rename
Intelligently rename tmux windows based on project context. (Previously called tmux-rename-windows.)
tmux-rename -n
tmux-rename
tmux-rename -s session-name
tmux-rename -f
tmux-rename -v
Behavior:
- Analyzes all panes in each window to determine context
- Checks for git repositories and uses repo name when appropriate
- Falls back to common directory path if panes span multiple repos
- Skips windows with custom names (unless -f flag used)
- Skips windows with automatic-rename enabled
- Handles duplicate names by adding numeric suffixes
Session and Layout Management
tmux-dev-window
Create a development window with standard three-pane layout.
tmux-dev-window
tmux-dev-window -s session-name
See docs/tmux-dev-window.md for detailed documentation.
tmux-session (alias: t)
Unified session management -- create, switch, link, and list sessions.
t
t myproject
t ~/Code/repo
t --link
t --link myproject
t --list
t --dev
t --first-only
Theme Management
tmux-theme-detect and tmux-theme-apply
Detect system appearance and apply matching tmux theme.
tmux-theme-detect
tmux-theme-apply light
See docs/theme-switching.md for details.
Interactive Tools
tmux-cheat
Display context-aware cheat sheets based on current pane's program.
tmux-cheat
Working with tmux Commands
Essential Commands Reference
Sessions:
tmux ls
tmux new -s name
tmux attach -t name
tmux rename-session -t old new
Windows:
tmux list-windows
tmux new-window -n name
tmux rename-window name
tmux select-window -t :0
Panes:
tmux list-panes
tmux split-window -h
tmux split-window -v
tmux select-pane -t :.0
Format Strings
When using tmux commands with -F flag:
#{session_name} - Session name
#{window_index} - Window index
#{window_name} - Window name
#{pane_id} - Unique pane identifier
#{pane_current_path} - Current directory
#{pane_current_command} - Running command
Example:
tmux list-panes -a -F '#{session_name}:#{window_index} #{window_name} #{pane_current_path}'
AI Integration via MCP
Reading Configuration First
ALWAYS read ~/.tmux.conf before using tmux commands to understand:
- Window numbering (may start at 1 instead of 0)
- Custom key bindings
- Pane navigation settings
- User-specific configurations
Using Dedicated Command Panes
Critical Rule: Always execute commands in dedicated command panes, never in panes running interactive programs.
Why: The tmux MCP server sends keystrokes. Commands sent to:
- Editors (vim, neovim): Become text input or trigger editor commands
- Interactive programs: Get consumed by the program
- File browsers: May create files with command text as names
Standard Pane Identification:
- List panes with current command:
tmux list-panes -F '#{pane_id} #{pane_current_command}'
- Find panes running shells (bash, zsh, fish)
- Use those panes for command execution
Verification Protocol
After executing any tmux command via MCP:
- Capture pane content to verify result
- Check for errors or unexpected behavior
- Confirm command executed as intended
- Acknowledge and correct if something went wrong
See docs/tmux-mcp.md for comprehensive MCP integration documentation.
Documentation Resources
Progressive disclosure documentation in docs/:
session-window-pane-management.md - Comprehensive tmux command reference
tmux-mcp.md - MCP server setup and AI integration guide
tmux-mcp-ai.md - Best practices for AI agents using tmux MCP
claude-code-interaction.md - Sending input to Claude Code sessions (paste handler, bracketed-paste race)
teammate-pane-layout.md - Cascading leader + teammate pane pattern for multi-agent workflows (inspired by Claude Code)
tmux-dev-window.md - Development window layout documentation
theme-switching.md - Appearance-based theme switching
cheat.md - Quick reference for tmux key bindings
clipboard.md - Clipboard integration
Configuration
Metool Package Structure
This tmux package follows metool conventions:
bin/ - Executable scripts (symlinked to ~/.metool/bin/)
shell/ - Shell functions, aliases, completions (sourced by metool)
config/ - Configuration files (symlinked to home directory)
docs/ - Documentation for progressive disclosure
See ~/Code/github.com/mbailey/metool/docs/conventions/package-structure.md for details.
Installation
mt install tmux
Common Workflows
Automatically Rename Windows
tmux-rename -n
tmux-rename
tmux-rename -s work
Set Up Development Session
tmux new -s project
tmux-dev-window
tmux attach -t project
tmux-dev-window
Quick Session Switch
t work
tmux ls
t project
Opening a Session in a Second Terminal
To view different windows of the same session from two terminals, use linked sessions:
t --link
t taskmaster
t taskmaster-2
Linked sessions auto-number: if taskmaster-2 exists, it creates taskmaster-3, etc.
The base session must already exist -- create it first with t if needed.
Best Practices
For AI Agents
- Always read
~/.tmux.conf first - Understand user configuration
- Verify pane types before execution - Check what program is running
- Use dedicated shell panes - Never execute in editor/program panes
- Capture and verify output - Check command results
- Respect window names - Don't rename custom-named windows without permission
Sending Input to Claude Code Instances
When sending input to another Claude Code session via tmux, text and Enter must be sent as separate commands:
tmux send-keys -t pane "message" Enter
tmux send-keys -t pane -l "message"
tmux send-keys -t pane Enter
This is how agents minion send works internally. The -l flag ensures the message text is sent literally without interpretation. Always verify the message was received by checking the pane content after sending.
Prefer using agents minion send when available, as it handles this correctly:
agents minion send m-worker "your message here"
For large pastes, bracketed-paste behaviour, and the race condition that
can swallow the submit, see docs/claude-code-interaction.md.
Identifying Your Own Pane ($TMUX_PANE)
Inside tmux, $TMUX_PANE holds the pane ID of the shell or program that
inherited the environment -- the pane you are in. #P and
display-message without a target return the active pane of the
current window, which may not be you.
echo "$TMUX_PANE"
tmux capture-pane -p -t "$TMUX_PANE"
See docs/session-window-pane-management.md for sibling-pane patterns.
For Users
- Name windows intentionally - Custom names won't be auto-renamed
- Use standard layouts - Consistent pane positions improve workflow
- Enable automatic-rename selectively - For windows that should update automatically
- Run
tmux-rename periodically - Keep window names synchronized with projects
Troubleshooting
Windows Not Being Renamed
Check:
- Does window have automatic-rename enabled? (
tmux show-window-options automatic-rename)
- Is window name custom (not a default command name)?
- Run with verbose flag to see reasoning:
tmux-rename -n -v
Pane Commands Going to Wrong Location
Solutions:
- List panes and their commands:
tmux list-panes -F '#{pane_id} #{pane_current_command}'
- Identify shell panes (bash, zsh, fish)
- Target correct pane ID when sending commands
- Read AI.md for best practices
Session Layout Issues
Check:
- Base-index setting:
tmux show-options -g base-index
- Pane-base-index:
tmux show-options -g pane-base-index
- Read user's ~/.tmux.conf for custom configurations
See Also