🎯

tmux

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill tmux

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/tmux
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/tmux/
  • All projects ~/.claude/skills/tmux/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

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

# 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

# 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:

# ~/.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):

# 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:

#!/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.

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.

# ~/.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

ErrorCauseSolution
Terminal colors washed out or italic text brokendefault-terminal not supporting true color in tmuxAdd set-option -ga terminal-overrides ",xterm-256color:Tc" to ~/.tmux.conf.
Mouse copy-paste copies line numbers across panesMouse drag copies raw terminal buffer instead of pane textHold Option (macOS) / Shift (Linux) while selecting, or use tmux vi copy mode (prefix + [).
sessions should be nested with care errorAttempting to launch tmux from within an existing tmux paneDetach first (prefix + d) or switch session via prefix + s.

References

More from this repository10