Line wrap failures in tmux over mosh typically stem from mismatched terminal width settings or missing escape sequences. The most effective fix involves ensuring the remote shell correctly reports its dimensions to tmux by setting the
TERM environment variable to
xterm-256color and configuring tmux to update this status dynamically. This aligns the client's rendering engine with the server's expectations, preventing text from spilling off-screen or breaking awkwardly.
Understanding the Root Cause
The issue arises because mosh acts as a wrapper around ssh, but it handles terminal resizing differently than standard ssh sessions. When you connect via mosh, the initial connection might establish a specific window size. However, if your local terminal emulator resizes, mosh notifies the server, but tmux might not immediately reflect this change in its internal state. Consequently, tmux continues to render output based on an outdated width, causing lines to wrap prematurely or not at all.
Furthermore, the
TERM variable plays a critical role. If tmux is set to a generic terminal type that does not support advanced wrapping features, or if mosh overrides it incorrectly, the rendering logic fails. Mosh clients often send specific escape codes to adjust the terminal properties, but tmux needs to be explicitly told to trust and propagate these changes to the applications running inside it.
Configuring Terminal Emulator Settings
Before diving into tmux configurations, ensure your local terminal emulator (such as iTerm2, Terminal.app, or GNOME Terminal) is sending the correct information to mosh. Most modern terminals allow you to specify the
TERM type in their preferences. You should set this to
xterm-256color. This setting ensures that both the local side and the remote side agree on the capabilities of the terminal, including line wrapping behavior.
If you are using a custom shell configuration, verify that you are not overriding the
COLUMNS or
LINES environment variables in your
.bashrc or
.zshrc. Hardcoding these values can prevent dynamic resizing from taking effect. Remove any static assignments for these variables to allow the system to calculate them automatically based on the actual window size.
Quitting Mosh Inside Tmux: A Tech Support Solution discusses related session management issues, which often overlap with configuration problems like incorrect terminal types. Ensuring your session environment is clean of hardcoded dimensions is a prerequisite for fixing wrap issues.
Tmux Configuration Adjustments
To resolve the line wrap problem within tmux, you need to adjust how tmux detects and updates the terminal size. Add the following lines to your
~/.tmux.conf file:
set -g default-terminal "xterm-256color"
set -g update-environment "TERM COLUMNS LINES"
setw -g aggressive-resize on
The
default-terminal option tells tmux what kind of terminal it is emulating. Setting it to
xterm-256color ensures compatibility with most modern tools. The
update-environment directive is crucial; it instructs tmux to sync the
TERM,
COLUMNS, and
LINES variables from the outer shell into the inner tmux environment whenever they change. Without this, tmux ignores the resize events sent by mosh.
The
aggressive-resize option forces tmux to attempt resizing even if some applications do not respond quickly to the
SIGWINCH signal. This is particularly helpful in unstable network conditions where mosh might delay resize notifications.
Verifying the Fix
After updating your configuration, restart tmux completely to apply the changes. Detach from any existing sessions (
Ctrl-b d) and kill the server process, then start a new one. Connect via mosh again and open a pane or window. Resize your local terminal window significantly wider and narrower. Observe whether the text wraps cleanly at the edge of the pane without cutting off mid-word or leaving excessive whitespace.
You can also check the current column count by running
echo $COLUMNS inside tmux. Compare this value with the actual width of your terminal. If they match, the environment variables are being synced correctly. If they do not match, review your
update-environment setting and ensure no shell scripts are overriding
COLUMNS after tmux has started.
For users experiencing other input-related glitches during these transitions, understanding how to manage keystrokes is vital. See
How to Increase Timeout for Chain Commands and Keystrokes in Tmux for insights on command latency that might mimic wrap errors.
Frequently Asked Questions
Why does line wrap work in SSH but fail in Mosh?
Mosh uses a different protocol for handling terminal state updates compared to SSH, which can lead to timing discrepancies in how resize signals are processed. While SSH sends immediate updates, mosh may buffer them slightly differently, requiring tmux to be more aggressively configured to catch these changes.
Can I fix this without editing .tmux.conf?
No permanent fix requires configuration changes because the default tmux settings do not always sync environment variables reliably over mosh connections. However, you can temporarily test the fix by manually exporting
COLUMNS and
LINES before starting tmux, though this is not scalable for regular use.
Does changing the terminal theme affect line wrap?
Changing themes does not directly impact the logical wrapping of text, but certain color schemes might make visual artifacts appear more pronounced. The core issue is always dimensional calculation, not aesthetic rendering, so focus on
TERM settings rather than colors.
What if my application still breaks lines incorrectly?
If tmux itself is wrapping correctly but your application (like vim or less) is not, the issue lies within that application's terminal detection. Ensure the application is aware of the correct
TERM variable and consider restarting it after tmux has fully initialized to pick up the new environment.
Is there a performance cost to enabling aggressive-resize?
The performance cost is negligible on modern systems. Aggressive-resize primarily affects how quickly tmux responds to window size changes, ensuring smooth user experience during rapid resizing events without adding noticeable CPU overhead.