gpakosz/.tmux (Oh My Tmux!): A Self-Contained tmux Configuration

What gpakosz/.tmux Solves and Who Should Use It

A default tmux installation works but looks minimal and requires manual configuration for features like mouse support, a readable status bar, and clipboard integration. gpakosz/.tmux is a single, curated configuration that adds all of those with no plugin manager required. It is designed for engineers who spend significant time in terminal sessions, particularly those who work over SSH or Mosh and want the status bar to show hostname and username without extra scripting. The README describes the configuration as 'self-contained, pretty and versatile.' The self-contained aspect is the practical advantage: there is no separate plugin repository to clone, no TPM to install, and no list of plugins to manage. The configuration ships as one .tmux.conf file and one .tmux.conf.local template for overrides. Supported platforms are Linux, macOS, FreeBSD, OpenBSD, and Windows via WSL or Cygwin, though the README notes WSL and Cygwin are not recommended.

The Symlink Architecture: Why the Main Config Is Read-Only

The install creates a symlink from your home directory's .tmux.conf (or the XDG equivalent) to the cloned repository's .tmux.conf file. The actual customization file, .tmux.conf.local, is copied rather than symlinked. This separation is intentional. When the repository receives an update, pulling the latest changes updates the main config through the symlink while leaving your .tmux.conf.local untouched. The README is explicit about this: 'You should never alter the main .tmux.conf or tmux.conf file. If you do, you're on your own.' Every personal customization belongs in .tmux.conf.local. If you want a setting from the main config to persist even when Oh My Tmux! would override it, append `#!important` to that line in your local file. For example, to force a specific default terminal:

set -g default-terminal "screen-256color" #!important

This directive tells the configuration processing logic not to overwrite that setting.

Installing Oh My Tmux! in Your Home Directory

There are two installation paths. The automatic path uses a curl one-liner:

curl -fsSL "https://github.com/gpakosz/.tmux/raw/refs/heads/master/install.sh#$(date +%s)" | bash

The manual path for installing in your home directory is:

cd
git clone --single-branch https://github.com/gpakosz/.tmux.git
ln -s -f .tmux/.tmux.conf
cp .tmux/.tmux.conf.local .

The `git clone --single-branch` flag avoids downloading any other branches. The `ln -s -f` command creates the symlink, forcing it even if a .tmux.conf already exists. The `cp` command places a writable copy of the override template in your home directory. If you prefer the XDG config directory, the README also documents installation in $XDG_CONFIG_HOME/tmux or ~/.config/tmux with corresponding paths for both the symlink and the copy. In those locations, the files do not have a leading dot in the name.

What the Configuration Adds Out of the Box

The feature list from the README covers practical terminal workflow improvements. C-a becomes a secondary prefix key, so both C-a and the default C-b work. The status bar follows a Powerline visual style and shows battery level, uptime, and SSH or Mosh-aware username and hostname. When connected over SSH, the hostname in the status bar updates to reflect the remote machine, and pane splitting reconnects to the remote server automatically. Mouse mode toggles with the prefix-m key combination. Any pane can be maximized into a new window with prefix-plus; the README notes this differs from tmux's built-in resize-pane -Z because the maximized pane can be split further. Clipboard copy works on Linux if xsel, xclip, or wl-copy is installed; on macOS it uses pbcopy. The configuration also integrates with PathPicker and Urlscan (or Urlview as a fallback) if those tools are present. For Powerline symbols, only fonts patched with Powerline glyphs are needed; the Powerline daemon is not required. The configuration also adds support for the Unicode escape sequences \uXXXX (Basic Multilingual Plane) and \UXXXXXXXX (supplementary plane), which is useful for displaying status line symbols that are not in the ASCII range. The README also mentions that the VISUAL or EDITOR environment variable set to vim will enable vi-style key bindings and further customize them beyond the defaults.

Known Display Bugs and Platform Constraints

The README documents two display problems worth knowing before installing. First, on Linux, a mismatch between the glib Unicode width function (g_unichar_iswide) and the glibc wcwidth function can break or duplicate the status bar. This happens when glib 2.50.1 or newer is paired with glibc older than 2.26. VTE-based terminal emulators use glib while tmux uses glibc, so the two can disagree on the display width of certain Unicode characters. Setting LC_CTYPE to a UTF-8 locale may help. The sample .tmux.conf.local has been updated to avoid characters whose width changed between Unicode 8.0 and 9.0 to reduce the chance of this issue. Second, on macOS with iTerm2, enabling 'Use Unicode version 9 character widths' in Preferences causes the same class of display problem. The README also requires tmux version 2.6 or higher, awk, perl (optionally with Time::HiRes), grep, and sed as runtime dependencies.

Plain Tmux Config vs. TPM vs. Oh My Tmux!

The most direct alternative to Oh My Tmux! is a hand-written ~/.tmux.conf. That approach gives complete control with no external dependency, but every feature (status bar, mouse support, clipboard) must be written from scratch. The maintenance burden grows as tmux releases change option names between versions. The other common approach is Tmux Plugin Manager (TPM), which installs plugins from separate Git repositories into ~/.tmux/plugins/. TPM supports a larger ecosystem of separately maintained plugins for specific features. The trade-off is that each plugin is an additional dependency to keep current, and the overall setup is composed from multiple repositories rather than one. Oh My Tmux! is self-contained by design: the entire configuration ships in a single repository, which simplifies updates at the cost of being less modular. Engineers who want a specific feature not covered by this configuration would need to add it in their .tmux.conf.local rather than pulling in a dedicated plugin.

Licence and Maintenance

The repository carries a dual licence: MIT and WTFPLv2 (as documented in LICENSE.MIT and LICENSE.WTFPLv2). Both are permissive and impose no restrictions on use, modification, or redistribution. The last push was on 2026-08-08, which is approximately seven weeks before this article was written. The repository has no GitHub releases; updates go directly to the master branch. For contributors, the .github/ directory contains issue and pull request templates. The configuration has no runtime dependencies beyond standard Unix utilities and tmux itself, which means there is no version pinning problem for the configuration files. The main ongoing maintenance cost for users is pulling updates when the tmux project adds or changes options that affect the configuration.

Editorial conclusion

Engineers who want a consistent tmux setup across multiple machines and prefer not to manage a plugin manager will find Oh My Tmux! a direct solution: symlink the config, copy the local override file, and start customizing. Developers on Windows should note that the README explicitly lists WSL and Cygwin as not recommended. The last push was on 2026-08-08. Before installing on a Linux machine, check whether the glib and glibc Unicode width versions are aligned to avoid the status line display bug documented in the README.

Frequently asked questions

Official sources

1. gpakosz/.tmux on GitHub
2. Issues
3. License: MIT
4. README