Tmux-Packet-Loss

Tmux-Packet-Loss is a plugin for Tmux that displays the percentage of packet loss on your connection. In reactive mode, it calculates loss using multiple rolling averages over recent checks and reports the highest value, making recent spikes visible while allowing them to decay over time. A simple rolling average mode can be selected via configuration.

• @packet-loss-weighted_average renamed to @packet-loss-reactive after clarifying that the approach is not a weighted average. The old variable is still supported for now, but triggers a warning advising migration.
• Added support for no network connection for all supported platforms - reported as 101
• Now uses both "journal_mode = WAL" and sqlite3 -cmd '.timeout 200' to avoid DB collisions
• Converted all scripts to POSIX, no more bash dependencies. This cuts down a lot on startup times, scripts/display-losses.sh is 3-4 times faster!
• Losses are displayed, but no stats are saved for the first 45 seconds. This avoids getting initial errors before the network is re-established saved into the history during a laptop resume.

Partial status bar configuration: #{battery_smart} #{packet_loss}%a %h-%d %H:%M

Plugin output takes no space when under @packet-loss-level_disp level.

The ~4 displays last 30 min average loss rate.

Display	With hist avg	Status
		under threshold
		low level losses
		alert level losses
		critical level losses

If @packet-loss-display_trend is yes, change since the previous check is indicated with a prefix character

Display	Status
	Increasing
	Stable
	Decreasing

The plugin runs a background process that periodically pings a host to measure packet loss. By default, it computes loss from multiple rolling averages over recent samples and reports the maximum value, making recent spikes more visible while allowing them to decay over time.

The monitor runs continuously. By default, it stops when no tmux clients are connected and restarts when one reconnects. Set @packet-loss-run_disconnected to yes to keep it running always. It exits when tmux shuts down.

Error codes (displayed as loss > 100%) indicate what went wrong:

• tmux 1.9+
• sqlite3

• Linux
• macOS
• Windows Subsystem for Linux (WSL)
• iSH
• Termux

Add the plugin to the list of TPM plugins in .tmux.conf:

set -g @plugin 'jaclu/tmux-packet-loss'

Hit prefix + I to fetch the plugin and source it. That's it!

Clone the repository:

git clone https://github.com/jaclu/tmux-packet-loss.git ~/clone/path

Add this line to the bottom of .tmux.conf:

run-shell ~/clone/path/packet-loss.tmux

Reload the Tmux environment with $ tmux source-file ~/.tmux.conf - that's it!

set -g @packet-loss-hist_avg_display  yes
set -g @packet-loss-run_disconnected  yes

# Single packet loss disappears from display in ~15s
set -g @packet-loss-level_disp   5

# Yellow background for alert/crit, so set alert color to blue instead
set -g @packet-loss-color_alert  colour21
set -g @packet-loss-color_bg     colour226

# Add spacer so plugin takes no space when there's no loss
set -g @packet-loss-suffix "| "

Ping count: Higher counts give better granularity (e.g., 2 pings can only show 0%, 50%, 100%) but take longer. Keep it short for real-time monitoring; use @packet-loss-hist_avg_display for longer-term trends.

Status interval: Set tmux's status-interval one less than @packet-loss-ping_count to sync updates (e.g., status-interval = 5 if ping_count = 6).

Clearing data: Delete the data folder to reset the database and restart the monitor—an easy way to clear history without touching SQL.

Reactive mode: When enabled (default), loss is computed from multiple rolling averages over recent samples (1–7) plus the full-history average, and the highest value is used. When disabled, loss is computed as the average of all samples.

Recommended alert thresholds to avoid false alarms from a single lost packet:

There are three tables

Each table contains two fields, time_stamp, and value. The time_stamp field is used to purge old records.

Use the included test script to simulate packet loss:

./scripts/test_data.sh

Run without params for help. The monitor restarts automatically 2 minutes after the last run.

Contributions are welcome, and they're appreciated. Every little bit helps, and credit is always given.

The best way to send feedback is to file an issue at tmux-packet-loss/issues

MIT