> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/tmux/tmux/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```c theme={null} /* * 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 ```bash theme={null} # 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): ```bash By ID theme={null} $ tmux select-window -t @5 ``` ```bash By index theme={null} $ tmux select-window -t :2 ``` ```bash By name theme={null} $ 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 | ```bash theme={null} # Select last window Prefix ! # Select next window Prefix n # Select previous window Prefix p ``` ## Window Naming From `window.c:407-412`: ```c theme={null} 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); } ``` ```bash theme={null} # Rename current window (within tmux) Prefix , # Or use command $ tmux rename-window new-name ``` ```bash theme={null} # 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: ```bash theme={null} # 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`: ```c theme={null} 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. ```bash theme={null} # 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: ```c theme={null} 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: ```bash theme={null} # 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`: ```c theme={null} void window_update_activity(struct window *w) { gettimeofday(&w->activity_time, NULL); alerts_queue(w, WINDOW_ACTIVITY); } ``` Enable activity monitoring: ```bash theme={null} # 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: ```c theme={null} 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: ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # Set window base index to 1 $ tmux set-option -g base-index 1 # Renumber windows sequentially $ tmux set-option -g renumber-windows on ```