Migrating from tmux.conf and TPM

Keep your current tmux config and TPM setup, then add tpane last:

# Existing options, bindings, and TPM plugins stay above this line.

run-shell -b 'tpane'

Create ~/.config/tmux/tpane/init.lua and move one section at a time. Source the tmux config once after adding the run-shell line. Changes to Lua files are reloaded automatically.

Move options

A tmux option:

set -g mouse on
set -g history-limit 50000
set -g mode-keys vi

becomes:

tpane.opt.mouse = true
tpane.opt.history_limit = 50000
tpane.opt.mode_keys = "vi"

Remove the original tmux lines after confirming the Lua version works. With tpane loaded last, its value wins at startup.

Move bindings

A tmux binding:

bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

becomes:

tpane.bind("h", tpane.pane.select("left"))
tpane.bind("j", tpane.pane.select("down"))
tpane.bind("k", tpane.pane.select("up"))
tpane.bind("l", tpane.pane.select("right"))

Raw tmux commands remain available when there is no tpane helper:

tpane.bind("R", "source-file ~/.tmux.conf ; display 'reloaded'")

Migrate TPM plugins

TPM plugins and tpane plugins are different systems. A TPM repository cannot be passed directly to tpane.use; external tpane plugins contain an init.lua entrypoint and use the tpane Lua API.

You can keep TPM while migrating. tpane has built-in alternatives for some common plugins:

TPM plugin	tpane built-in
tmux-plugins/tmux-sensible	tpane.use("sensible")
christoomey/vim-tmux-navigator	tpane.use("vim-navigator")
tmux-plugins/tmux-yank	tpane.use("yank")

Replace and test one plugin before removing its TPM declaration. Continue using TPM for plugins without a tpane equivalent.

Migrate the status bar last

tpane.statusline takes control of tmux's status format. Move the status bar after options, bindings, and plugins so it is easier to compare the old and new configuration.

tpane.statusline {
  left = { tpane.widgets.session, tpane.widgets.tabs },
  right = { tpane.widgets.clock },
}

See Status bar for widgets and styling.

Roll back

Remove this line from the tmux config:

run-shell -b 'tpane'

Removing the line does not undo settings already applied to a running tmux server. Finish any running sessions and restart the tmux server to return fully to the remaining configuration. The original tmux and TPM configuration can stay in place during migration, so rollback does not require reconstructing it.

See Install to remove the binary and tpane data.