gpakosz/.tmux

Project Overview

.tmux — published under the banner "Oh my tmux!" — is a self-contained, batteries-included configuration for tmux, the terminal multiplexer. Instead of building a .tmux.conf line by line over months, you clone one repository, symlink one file, and immediately get a polished status line, sane keybindings, and clipboard integration. The whole thing is plain tmux configuration plus embedded shell helpers, which is why GitHub classifies the repo as Shell.

It is a configuration, not a program. That matters for how you evaluate it: there is no daemon to run, no binary to update, and the "API" is a documented set of variables you override in a separate .tmux.conf.local file. The project requires tmux 2.6 or newer and runs anywhere tmux runs — Linux, macOS, and the BSDs.

Use it when you want a strong default setup you can layer personal tweaks on top of. Skip it if you already have a heavily customized config you love — merging the two is manual work, and this project assumes it owns the base layer.

Key Challenges Addressed

A hand-rolled tmux setup fails in predictable ways. This config targets those failure modes directly:

• Stock defaults are spartan. Out of the box, tmux gives you a bare status bar and keybindings that fight muscle memory. .tmux ships a full theme, h/j/k/l pane navigation, and splits on - and _ so you stop reaching for awkward default chords.
• Dotfiles rot when updates require manual merges. The two-file design — .tmux.conf owned by the project, .tmux.conf.local owned by you — means git pull updates the engine without touching your overrides.
• Clipboard integration breaks differently on every OS. Setting tmux_conf_copy_to_os_clipboard=true routes copy-mode yanks to the system clipboard using the right tool for your platform instead of leaving text stranded in tmux's internal buffer.
• Status-line eye candy usually demands patched fonts. The powerline-style separators are plain variables, so you can swap them for ASCII characters if your terminal font lacks the glyphs.

Getting Started

Installation is four commands:

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

Then start tmux. The symlink makes the project's .tmux.conf your live config; the copied .tmux.conf.local is yours to edit freely. From inside tmux, <prefix> e opens .tmux.conf.local in your $EDITOR and reloads the configuration when you save, and <prefix> r reloads manually.

Sharp edges you will hit in the first hour:

• If your tmux is older than 2.6, the config will not load correctly. Run tmux -V before installing and upgrade through your package manager first.
• If your terminal font lacks powerline glyphs, the status-line separators render as boxes or question marks. Install a powerline-patched or Nerd Font first, or set tmux_conf_theme_left_separator_main and its sibling separator variables to plain characters in .tmux.conf.local.
• If you edit .tmux.conf instead of .tmux.conf.local, the next git pull wipes your changes. Treat .tmux.conf as read-only, always.
• On Linux, copying to the OS clipboard silently does nothing without xsel or xclip installed. Install one of them before enabling tmux_conf_copy_to_os_clipboard=true.

Features and Use Cases

The day-to-day wins are ergonomic, not flashy:

• A status line with useful telemetry. Battery level, date and time, and username@hostname display — with awareness of SSH sessions, so you can tell a remote tmux from a local one at a glance. This alone prevents the classic mistake of killing a window on the wrong machine.
• Mouse support on a toggle. <prefix> m flips mouse mode on and off. Keep it off for fast keyboard-driven work, flip it on when you need to resize panes or scroll with a trackpad.
• Pane and window ergonomics. Maximize the current pane into its own window with <prefix> + and restore it the same way. Set tmux_conf_new_window_retain_current_path=true so new windows open where you are instead of in your home directory.
• Vi-style copy mode. <prefix> Enter drops you into copy mode with vi-flavored bindings, and yanks can go straight to the system clipboard once you enable the clipboard variable.

The most realistic deployment scenario: you keep .tmux.conf.local in your dotfiles repo and clone .tmux onto every server you SSH into. Because the project is self-contained and needs nothing beyond tmux and a shell, the same setup works identically on your laptop and a bare VM.

Ecosystem and Dependencies

Plugin support comes through tpm, the standard tmux plugin manager, which .tmux integrates with directly: declare plugins in .tmux.conf.local and control update behavior with tmux_conf_update_plugins_on_launch. You do not install tpm separately by hand the way you would on a stock config.

Theme packs like catppuccin/tmux and dracula/tmux target stock tmux and overlap with .tmux's own theming layer. Don't stack them — pick one theming system, because two systems writing the status line produces flicker and lost segments.

Hard dependencies are minimal by design: tmux 2.6+, a POSIX shell, and optionally xsel or xclip on Linux for clipboard support.

Architectural Overview

The architecture is a deliberate engine/data split. .tmux.conf is the engine: keybindings, theme machinery, and embedded shell helpers invoked through tmux's run-shell. .tmux.conf.local is the data: tmux_conf_* variables plus any raw tmux commands you append at the bottom. On startup, the engine reads your variables and generates the status line and behavior from them.

This split is why the project survives updates that destroy other dotfile setups. The upgrade path is git pull on the engine while your data file never changes. It also makes your customization reviewable: everything you did lives in one short file, not scattered through 600 lines of someone else's config.

The cost of the design is indirection. When something misbehaves, you debug generated configuration rather than lines you wrote, and the embedded shell helpers are dense reading.

Pros and Cons

Pros:

• Two-minute setup that replaces months of incremental config tinkering.
• Update-safe customization model — git pull never touches your overrides.
• No runtime dependencies beyond tmux and a shell, so it deploys cleanly to servers.
• Very wide usage (25,000+ stars as of 2026-06-12) means the issue tracker already covers most edge cases you'll hit.

Cons:

• Opinionated keybindings: if you have existing tmux muscle memory, you will fight the defaults until you re-map them in .tmux.conf.local.
• It owns the base layer. You cannot compose it with another full configuration; migrating an existing config into .tmux.conf.local is manual.
• The generated, shell-driven status line is harder to debug than a flat config when a segment renders wrong.
• Powerline aesthetics depend on font support; without the right glyphs the default theme looks broken.

Comparison and Alternatives

The honest comparison set spans two categories: other ready-made tmux configurations, and tools that replace the need for one. tmux-sensible is the minimalist option — a small set of uncontroversial defaults you add to your own config rather than a full replacement. tmux-config is a comparable batteries-included configuration with its own theming and keybinding opinions. tpm is not a config at all but the plugin manager you'd use to assemble your own setup piece by piece. catppuccin/tmux covers just the theming slice. And zellij sidesteps tmux entirely — a separate multiplexer with usable defaults built in, at the cost of leaving the tmux ecosystem.

The best overall alternative is tpm. It is the most mature and best-documented piece of the tmux ecosystem, and building your own config on tpm plus a few plugins gives you the customization .tmux abstracts away while staying on the standard upgrade path everyone else uses.

Conclusion

If you spend hours a day in a terminal but have never invested in a real tmux setup, install Oh my tmux! today — it is the fastest route from stock tmux to a configuration you'd actually keep. Start with the official README, which documents every tmux_conf_* variable you can override. Put every customization in .tmux.conf.local and nowhere else.

Do not edit .tmux.conf directly: the file is designed to be replaced wholesale by git pull, so any change you make there is silently lost on the next update. The same applies to forking the repo just to tweak the theme — the variables in .tmux.conf.local already cover it. Do this first: run tmux -V to confirm you're on tmux 2.6 or newer, then run the four-line install from the Getting Started commands above.