Skip to content

tmux-config

A tmux configuration that is readable, portable, and fast — and documented well enough that you can change any part of it without reading the tmux manual first.

It runs on macOS, Linux, WSL2, and MSYS2/Cygwin from the same files, with no plugins required.

Why another tmux config

Most shared tmux configs fall into one of two traps: a 400-line file where every setting is entangled with every other, or a plugin stack where a dozen repositories decide your behaviour and any of them can break on update.

This one takes a different position:

Everything you would normally want to change lives in one file, as a named option with a documented default.

config/00-options.conf
set -g @cfg_theme  "catppuccin-mocha"
set -g @cfg_prefix "C-b"
set -g @cfg_mouse  "on"

Change a value, press Ctrl+B R, and it applies. You do not need to know which tmux option, which key table, or which of the seven pane-*-style settings implements it.

What you get

  • One file to configure

    Every setting is a named @cfg_* option with its default, its accepted values, and the reason it is set that way written next to it.

    Configuration

  • Six themes, ten variables

    Themes define ten colours and nothing else. Writing your own is a twenty-line file that touches no layout.

    Theming

  • Clipboard that works everywhere

    Detects macOS, Wayland, X11, WSL, and Cygwin, plus OSC 52 so copy works over SSH.

    Clipboard

  • Degrades instead of breaking

    True colour, Unicode glyphs and clipboard route are detected, not assumed. No UTF-8 locale? ASCII separators, automatically.

    Capabilities

  • Plugins vendored, not fetched

    Pinned inside the repo via git subtree. No plugin manager, no download at startup, works offline.

    Plugins

  • No forks in the hot path

    Conditionals resolve at parse time. The status bar runs no subprocesses. Plugins are off by default.

    Architecture

Quick start

git clone https://github.com/MichaelWeissDEV/tmux-config.git ~/.config/tmux
cd ~/.config/tmux && ./install.sh

The installer backs up anything already there, checks your tmux version, and verifies the config loads before it finishes. Then:

tmux

Full instructions, including the Windows situation, are in Installation.

Windows users, read this first

tmux does not run on native Windows — not in PowerShell, not in cmd.exe, not in Windows Terminal by itself. It needs WSL2, MSYS2, or Cygwin. This config supports all three, but the requirement is real and no configuration can remove it. See the platform matrix.

The three files that matter

File What it is for
config/00-options.conf Change settings here. Every tunable, with documented defaults.
local.conf Add your own things here. Gitignored, loaded last, survives git pull. Start from local.conf.example, which ships every recipe commented out.
tmux.conf The loader. You should not need to edit it.

Everything else is a module that reads your options and applies them.

Requirements

  • tmux 3.3 or newer. Checked at startup with a clear message if not. (Why 3.3?)
  • A UTF-8 locale, for the status bar separators. (What happens without one)
  • That is all. No Nerd Font, no Python, no plugin manager.

Where to go next