Skip to content
Skills Library
Programming · Learning & explanation

tmux

/tmux

Expert tmux assistance covering terminal multiplexing, session management, window/pane layouts, tmux.conf customization, and scriptable session automation via tmuxp. Use when managing persistent remote sessions, splitting terminal windows, organizing multi-project workflows, or configuring custom keybindings.

Licence
MIT
Last repository change
01.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 01.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Expert tmux assistance covering terminal multiplexing, session management, window/pane layouts, tmux.conf customization, and scriptable session automation via tmuxp. Use when managing persistent remote sessions, splitting terminal windows, organizing multi-project workflows, or configuring custom keybindings.

Original author description

Expert tmux assistance covering terminal multiplexing, session management, window/pane layouts, tmux.conf customization, and scriptable session automation via tmuxp. Use when managing persistent remote sessions, splitting terminal windows, organizing multi-project workflows, or configuring custom keybindings.

How it works

  1. When to Use
  2. Quick Start
  3. Core Concepts
  4. Common Patterns
  5. Best Practices
  6. Troubleshooting
  7. References
Original SKILL.md headings · 203 lines, 852 words
SKILL.md preview
---
name: tmux
description: Expert tmux assistance covering terminal multiplexing, session management, window/pane layouts, tmux.conf customization, and scriptable session automation via tmuxp. Use when managing persistent remote sessions, splitting terminal windows, organizing multi-project workflows, or configuring custom keybindings.
---

# Tmux

Tmux decouples your terminal session from the window. Detach, go home, SSH in, attach, and your cursor is exactly where you left it. v3.5 adds extended keys.

## When to Use

- **Terminal Session Persistence**: Keeping background jobs, tests, and servers running across SSH disconnects and laptop restarts.
- **Complex Split-Pane Workspaces**: Organizing multi-window terminals with synchronized panes, log tailing, and editor buffers.
- **Remote Pair Programming**: Sharing a live terminal session with remote teammates over SSH with zero latency.
- **Scripted Environment Automation**: Bootstrapping reproducible development environments using `tmuxinator` or custom bash scripts.

## Quick Start

### 1. Minimal ~/.tmux.conf

```tmux
# Remap prefix from 'C-b' to 'C-a'
unbind C-b
set-option -g prefix C-a
bind-key C-a send-prefix

# Split panes using | and -
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

# Enable mouse mode & 256 colors
set -g mouse on
set -g default-terminal "tmux-256color"
```

### 2. Session Management

```bash
# Create new session
tmux new -s dev

# List active sessions
tmux ls

# Attach to session
tmux attach -t dev
```

## Core Concepts

### Production Tmux Configuration (`~/.tmux.conf`)

Configuring modern true-color support, mouse navigation, prefix remapping, and Vim-style pane switching:

```text
# ~/.tmux.conf
# Remap prefix from 'C-b' to 'C-a'
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Quality of Life
set -g mouse on
set -g history-limit 50000
set -g escape-time 0
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on

# True Color Support
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Split panes using | and -
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

# Reload config
bind r source-file ~/.tmux.conf \; display-message "Tmux config reloaded!"
```

### Tmux Plugin Manager (TPM) & Session Persistence

Installing TPM and configuring automatic session restore (`tmux-resurrect` and `tmux-continuum`):

```text
# Add to bottom of ~/.tmux.conf
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

# Automatic restore on tmux start
set -g @continuum-restore 'on'

run '~/.tmux/plugins/tpm/tpm'
```

### Programmatic Session Bootstrapping Script

Creating a multi-window development workspace automatically:

```bash
#!/usr/bin/env bash
SESSION_NAME="core-api"

# Check if session exists
tmux has-session -t $SESSION_NAME 2>/dev/null

if [ $? != 0 ]; then
  # Create new detached session
  tmux new-session -d -s $SESSION_NAME -n "editor"
  tmux send-keys -t $SESSION_NAME:1 "nvim ." C-m

  # Window 2: Servers & Logs
  tmux new-window -t $SESSION_NAME:2 -n "services"
  tmux send-keys -t $SESSION_NAME:2 "docker compose up" C-m
  tmux split-window -h -t $SESSION_NAME:2
  tmux send-keys -t $SESSION_NAME:2.2 "npm run dev" C-m

  # Window 3: Terminal / Git
  tmux new-window -t $SESSION_NAME:3 -n "shell"
fi

# Attach to session
tmux attach-session -t $SESSION_NAME
```

## Common Patterns

### Vim-Style Pane Navigation

**Problem**: Navigate between split terminal panes using standard `h`, `j`, `k`, `l` directional keys.  
**Solution**: Bind keys in `~/.tmux.conf`.

```tmux
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Fast resize with capital letters
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5
```

### Automated Workspace Layout with tmuxp

**Problem**: Rebuild a multi-window development layout (server, client, logs) with one command.  
**Solution**: Define YAML workspace file for `tmuxp`.

```yaml
# ~/.tmuxp/myproject.yaml
session_name: myproject
windows:
  - window_name: code
    layout: main-vertical
    panes:
      - nvim
      - git status
  - window_name: server
    panes:
      - npm run dev
      - docker compose logs -f
```

Run `tmuxp load myproject` to restore.

## Best Practices

**Do**:

- Set `escape-time 0` in `~/.tmux.conf` to eliminate input lag when using Neovim/Vim inside Tmux.
- Enable `renumber-windows on` so window indexes remain sequential (1, 2, 3...) when closing intermediate tabs.
- Leverage **TPM** with `tmux-resurrect` to persist active layouts and terminal state across machine reboots.
- Use `#{pane_current_path}` when splitting panes so new panes open in the current working directory.

**Don't**:

- Leave detached sessions consuming gigabytes of forgotten Docker build or process logs; kill dead sessions with `tmux kill-session`.
- Configure conflicting hotkeys between Tmux prefix and shell shortcuts (e.g. `C-a` for start of line).
- Run Tmux inside another nested Tmux session over SSH without adjusting the escape prefix.

## Troubleshooting

| Error                                             | Cause                                                       | Solution                                                                                          |
| ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Terminal colors washed out or italic text broken  | `default-terminal` not supporting true color in tmux        | Add `set-option -ga terminal-overrides ",xterm-256color:Tc"` to `~/.tmux.conf`.                   |
| Mouse copy-paste copies line numbers across panes | Mouse drag copies raw terminal buffer instead of pane text  | Hold `Option` (macOS) / `Shift` (Linux) while selecting, or use tmux vi copy mode (`prefix + [`). |
| `sessions should be nested with care` error       | Attempting to launch tmux from within an existing tmux pane | Detach first (`prefix + d`) or switch session via `prefix + s`.                                   |

## References

- [Tmux Wiki](https://github.com/tmux/tmux/wiki)

Versions

RepositoryScoreLicence
This page · G1Joshi/Agent-Skills100MIT
DaRacci/nix-config100MIT
julianobarbosa/claude-code-skills100MIT
nicknisi/claude-plugins100MIT
hkuds/nanobot96MIT
rachebtms/Cirno96MIT

Database snapshot: 13.11.2026 · package version 78afd48ef3d5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95tmux-cheatsheet
    Use when the user needs tmux commands: creating and attaching sessions, windows and panes, splitting and resizing, copy mode and scrollback search, the tmux.conf file, and keeping work alive after the terminal closes.
  • 95tmux-start
    Start issue work in a new tmux window with its own worktree. Use when the user has tmux running and wants issue startup to continue outside the current session. SKIP when not inside a tmux session ($TMUX unset) or when the user wants to work in the current session; use start-issue directly.
  • 100tmux-automation
    Drive CLI tests inside isolated tmux/byobu sessions with ai-monitor integration. Use when asked to "test this CLI", "run it in tmux", "automate a terminal session", "capture the output of an interactive command", "send keystrokes to a session", or to exercise a plugin or…
  • 100iterm2
    iTerm2 terminal emulator and tmux multiplexer expertise. USE WHEN user mentions iTerm2, tmux, terminal sessions, split panes, window management, OR terminal productivity on macOS.
  • 100session
    Worktree and session management. Use for "new session", "worktree", "tmux", and "session management".
  • 100tmux-organize
    Inspect every tmux pane, infer what it's about, then rename + reorder windows/sessions accordingly. Use when the user says "organize my tmux", "rename my windows based on what's in them", "clean up tmux", "auto-name tmux", "tidy tmux sessions", or invokes `/tmux-organize`.…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.