tmux
Understand window and pane layout of tmux and use that context to answer questions like "what is happening in the bottom pane?"
When & Why to Use This Skill
The Tmux Integration skill empowers Claude to navigate and interpret complex terminal layouts within tmux sessions. By analyzing window structures and pane contents, it allows users to interact with their terminal environment using natural language and spatial references, significantly streamlining CLI-based workflows and debugging processes.
Use Cases
- Multi-pane Debugging: Ask Claude to analyze error logs or stack traces in a specific side pane while you continue writing code in the primary pane.
- Real-time Process Monitoring: Use spatial commands like 'What is happening in the bottom pane?' to get summaries of long-running build processes or server logs.
- Context-Aware Terminal Assistance: Enable Claude to understand the full context of your workspace by letting it read and correlate information across multiple active terminal windows.
- Hands-free Terminal Navigation: Map natural language references (e.g., 'left pane', 'top-right') to specific tmux pane IDs to extract data without manual copy-pasting.
| name | tmux |
|---|---|
| description | Understand window and pane layout of tmux and use that context to answer questions like "what is happening in the bottom pane?" |
Tmux Integration Skill
Overview
This skill enables Claude to understand and interact with tmux panes in the user's active terminal session. Claude can identify pane positions, read pane contents, and respond to spatial references like "left pane" or "bottom pane."
Core Capabilities
1. Understanding Pane Layout
Claude uses two commands to understand the tmux window structure:
Get pane list with active status:
tmux list-panes
Output format:
0: [175x62] [history 398/2000, 288087 bytes] %1
1: [98x37] [history 91/2000, 125313 bytes] %14
2: [98x24] [history 1886/2000, 1548986 bytes] %17 (active)
- Index: Pane number (0, 1, 2...)
- Dimensions: [width x height]
- Pane ID: %N identifier
- (active): Marks the currently active pane
Get layout structure:
tmux display-message -p '#{window_layout}'
Output format:
00ef,274x63,0,0{175x63,0,0,1,98x63,176,0[98x38,176,0,14,98x24,176,39,17]}
This layout string encodes:
- Checksum (00ef)
- Window dimensions (274x63)
- Pane tree structure with positions and IDs
- Nested structure shows vertical
[...]and horizontal{...}splits
2. Reading Pane Contents
# Capture the active pane
tmux capture-pane -p
# Capture a specific pane by ID
tmux capture-pane -p -t %14
# Capture with scrollback history
tmux capture-pane -p -S -1000
Workflow
When the user references panes spatially (e.g., "left pane", "top pane", "bottom right"):
- Identify the context: Recognize this is a tmux-related request
- Get layout information: Run both
tmux list-panesandtmux display-message -p '#{window_layout}' - Parse the layout:
- Determine pane positions from the layout string
- Map spatial references to pane IDs
- The layout string format:
{horizontal}splits and[vertical]splits - Coordinates in format: width x height, x-offset, y-offset, pane-id
- Identify target pane:
- "left/right" refers to horizontal position
- "top/bottom" refers to vertical position
- "active" refers to the pane marked (active)
- Read pane content: Use
tmux capture-pane -p -t %IDwith the identified pane ID - Respond to user's request based on the pane content
Spatial Reference Examples
Two panes side-by-side:
- "left pane" = pane at smaller x-offset
- "right pane" = pane at larger x-offset
Two panes stacked:
- "top pane" = pane at smaller y-offset
- "bottom pane" = pane at larger y-offset
Complex layouts (3+ panes):
- Combine directional references
- Use the layout tree structure to understand relationships
- When ambiguous, ask user for clarification or use pane index
Error Handling
- If tmux is not running: Inform user that tmux session is not detected
- If layout is ambiguous: Ask user to specify by pane index (0, 1, 2...)
- If pane reference is unclear: List available panes with their approximate positions
Best Practices
- Always verify active pane first before making assumptions
- Parse layout systematically: Start from window dimensions, then work through the split tree
- Provide context: When referencing panes, briefly mention which pane (by index or position) you're examining
- Efficient reads: Only capture pane contents when necessary for the task
- User feedback: If interpreting spatial references, confirm with user (e.g., "Looking at pane 1 (left pane)...")
Example Interactions
User: "Check the error in the left pane" Claude process:
- Run
tmux list-panesandtmux display-message -p '#{window_layout}' - Parse to find left-most pane (e.g., pane %1)
- Run
tmux capture-pane -p -t %1 - Analyze the captured content for errors
- Report findings
User: "What's running in the bottom pane?" Claude process:
- Identify pane with largest y-offset
- Capture that pane's content
- Examine for running processes/commands
- Report what's visible