Windows

Understanding tmux windows as full-screen containers for panes

Overview

A window in tmux occupies the entire screen and may be split into rectangular panes. Each window is a full-screen container that belongs to one or more sessions and can display multiple terminal panes.

From the man page (tmux.1:48-62):

Each session has one or more windows linked to it. A window occupies the entire screen and may be split into rectangular panes, each of which is a separate pseudo terminal.

Window Architecture

From window.c:36-53, windows are implemented as:

/*
 * Each window is attached to a number of panes, each of which is a pty. This
 * file contains code to handle them.
 *
 * A pane has two buffers attached, these are filled and emptied by the main
 * server poll loop. Output data is received from pty's in screen format,
 * translated and returned as a series of escape sequences and strings via
 * input_parse (in input.c).
 *
 * Windows are stored directly on a global array and wrapped in any number of
 * winlink structs to be linked onto local session RB trees. A reference count
 * is maintained and a window removed from the global list and destroyed when
 * it reaches zero.
 */

Creating Windows

From window.c:294-339, window creation involves:

1. Assigning a unique window ID (prefixed with @)
2. Setting initial dimensions and pixel sizes
3. Initializing the panes list
4. Creating the options hierarchy
5. Recording creation and activity time

# Create new window (within tmux)
Prefix c

# Create window with name
$ tmux new-window -n server

# Create window with command
$ tmux new-window -n vim 'vim'

Window Identification

Windows can be identified by:

• Window ID: Prefixed with @ (e.g., @0, @1) - unique and unchanging
• Window index: Numeric position in session (e.g., 0, 1, 2)
• Window name: Descriptive name set by user or automatic naming

From the man page (tmux.1:787-845):

By ID

$ tmux select-window -t @5

$ tmux select-window -t :2

$ tmux select-window -t mywindow

Special Window Tokens

From tmux.1:835-845:

Token	Shorthand	Meaning
{start}	^	The lowest-numbered window
{end}	$	The highest-numbered window
{last}	!	The last (previously current) window
{next}	+	The next window by number
{previous}	-	The previous window by number

# Select last window
Prefix !

# Select next window
Prefix n

# Select previous window  
Prefix p

Window Naming

From window.c:407-412:

void
window_set_name(struct window *w, const char *new_name)
{
    free(w->name);
    utf8_stravis(&w->name, new_name, VIS_OCTAL|VIS_CSTYLE|VIS_TAB|VIS_NL);
    notify_window("window-renamed", w);
}

Manual Naming

# Rename current window (within tmux)
Prefix ,

# Or use command
$ tmux rename-window new-name

Automatic Naming

# Enable automatic renaming
$ tmux set-option -w automatic-rename on

# Disable automatic renaming
$ tmux set-option -w automatic-rename off

# Customize rename format
$ tmux set-option -g automatic-rename-format '#{pane_current_command}'

Window Navigation

Key Bindings

From the man page default key bindings (tmux.1:307-348):

• Prefix 0-9 - Select windows 0 to 9
• Prefix c - Create a new window
• Prefix , - Rename the current window
• Prefix & - Kill the current window
• Prefix n - Change to the next window
• Prefix p - Change to the previous window
• Prefix l - Move to the previously selected window
• Prefix w - Choose the current window interactively
• Prefix f - Prompt to search for text in open windows

Switching Windows

From session.c:417-466, window switching maintains a “last window” stack:

# Next window
$ tmux next-window

# Previous window  
$ tmux previous-window

# Last window
$ tmux last-window

# Select by index
$ tmux select-window -t :3

Window Linking

Windows can be linked to multiple sessions through the winlink structure. From window.c:98-133:

struct winlink *
winlink_find_by_window(struct winlinks *wwl, struct window *w)
{
    struct winlink *wl;
    
    RB_FOREACH(wl, winlinks, wwl) {
        if (wl->window == w)
            return (wl);
    }
    return (NULL);
}

A window maintains a reference count and is only destroyed when no sessions link to it.

# Link window from another session
$ tmux link-window -s other-session:2 -t :4

# Unlink window (doesn't destroy it)
$ tmux unlink-window -t :4

Window Resizing

From window.c:414-431, windows can be resized:

void
window_resize(struct window *w, u_int sx, u_int sy, int xpixel, int ypixel)
{
    log_debug("%s: @%u resize %ux%u (%ux%u)", __func__, w->id, sx, sy,
        xpixel == -1 ? w->xpixel : (u_int)xpixel,
        ypixel == -1 ? w->ypixel : (u_int)ypixel);
    w->sx = sx;
    w->sy = sy;
    if (xpixel != -1)
        w->xpixel = xpixel;
    if (ypixel != -1)
        w->ypixel = ypixel;
}

Window size is determined by the smallest attached client, unless size constraints are set:

# Set manual window size
$ tmux set-option -w window-size manual
$ tmux resize-window -x 120 -y 40

# Set to largest client
$ tmux set-option -w window-size largest

# Set to smallest client (default)
$ tmux set-option -w window-size smallest

Window Monitoring

Activity Monitoring

From window.c:288-292:

void
window_update_activity(struct window *w)
{
    gettimeofday(&w->activity_time, NULL);
    alerts_queue(w, WINDOW_ACTIVITY);
}

Enable activity monitoring:

# Monitor window for activity
$ tmux set-option -w monitor-activity on

# Get notification on activity  
$ tmux set-option -g visual-activity on

Window Flags

From window.c:877-904, windows display flags in the status line:

const char *
window_printable_flags(struct winlink *wl, int escape)
{
    static char flags[32];
    int pos = 0;
    
    if (wl->flags & WINLINK_ACTIVITY)
        flags[pos++] = '#';     // Activity in window
    if (wl->flags & WINLINK_BELL)
        flags[pos++] = '!';     // Bell in window
    if (wl->flags & WINLINK_SILENCE)
        flags[pos++] = '~';     // Silence (no activity)
    if (wl == s->curw)
        flags[pos++] = '*';     // Current window
    if (wl == TAILQ_FIRST(&s->lastw))
        flags[pos++] = '-';     // Last window
    if (wl->window->flags & WINDOW_ZOOMED)
        flags[pos++] = 'Z';     // Zoomed
    
    return (flags);
}

Window Options

Windows have their own option scope:

# Set window option
$ tmux set-option -w aggressive-resize on

# Set global window option
$ tmux set-option -g -w pane-base-index 1

# Show window options
$ tmux show-options -w

Common window options:

• automatic-rename - Automatically rename windows
• aggressive-resize - Resize based on active client
• monitor-activity - Monitor for activity
• window-status-format - Format for window in status line
• pane-base-index - Starting index for panes

Moving and Swapping Windows

# Move window to different index
$ tmux move-window -s :2 -t :5

# Swap two windows
$ tmux swap-window -s :1 -t :3

# Move window to another session
$ tmux move-window -s my-session:2 -t other-session:5

Best Practices

1. Use meaningful names: Name windows based on their purpose
2. Organize logically: Keep related panes in the same window
3. Monitor activity: Enable monitoring for background windows
4. Set base index: Start window numbering at 1 for easier keyboard access
5. Use window linking: Share windows between sessions when appropriate

# Set window base index to 1
$ tmux set-option -g base-index 1

# Renumber windows sequentially
$ tmux set-option -g renumber-windows on