Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/erickm13/Salchipapa.Dots/llms.txt

Use this file to discover all available pages before exploring further.

Tmux is the alternative terminal multiplexer option in Salchipapa.Dots. Its configuration lives at SalchipapaTmux/tmux.conf and is symlinked to ~/.config/tmux by the installer. The setup uses TPM (Tmux Plugin Manager) to handle all plugins declaratively, rebinds the prefix to Ctrl+a, adds seamless Neovim pane navigation via vim-tmux-navigator, enables session persistence with tmux-resurrect, and includes a floating scratch session toggled with Alt+g. The default shell is the Homebrew-managed Zsh at /home/linuxbrew/.linuxbrew/bin/zsh.

​
Installation

1

Create the symlink

Link the config directory into the standard tmux XDG location:
ln -s ~/Salchipapa.Dots/SalchipapaTmux ~/.config/tmux
2

Clone TPM

TPM (Tmux Plugin Manager) must be present before launching tmux:
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
3

Install plugins inside tmux

Open a tmux session, then press the plugin-install binding:
<prefix>+I
That is Ctrl+a followed by capital I. TPM will clone all listed plugins and source them.
You must complete this step the first time you open tmux after cloning TPM. Until plugins are installed, the Gruvbox theme and vim-tmux-navigator bindings will not be active. Subsequent startups load plugins automatically via the run -b '~/.tmux/plugins/tpm/tpm' line at the end of tmux.conf.

​
Plugins

All plugins are managed by TPM and declared with set -g @plugin in tmux.conf.

tmux-plugins/tpm

Tmux Plugin Manager — bootstraps and manages all other plugins. Clone it manually once (step 2 above); after that it self-manages.

tmux-plugins/tmux-sensible

Sensible defaults — a community-agreed baseline of settings (UTF-8, larger history, faster key repeat, etc.) that avoids common tmux gotchas.

christoomey/vim-tmux-navigator

Vim-tmux navigator — Ctrl+h/j/k/l moves between tmux panes and Neovim splits transparently. No mode-switching required.

tmux-plugins/tmux-resurrect

Session save/restore — persists tmux sessions, windows, and pane layouts across system reboots. Save: <prefix>+Ctrl+s. Restore: <prefix>+Ctrl+r.

alexwforsythe/tmux-which-key

Which-key — displays a popup listing available key bindings after a short pause following the prefix key, making keybind discovery easy.

egel/tmux-gruvbox

Gruvbox Dark theme — applies the Gruvbox dark color scheme to the status bar, pane borders, and mode indicators. Configured with set -g @gruvbox 'dark'.

​
Key Bindings

​
Prefix

The prefix has been rebound from the default Ctrl+b to Ctrl+a (screen-style): 
unbind C-b
set -g prefix C-a
bind C-a send-prefix

​
Pane Splitting

BindingAction
<prefix>+vVertical split (side-by-side), opens in current pane’s directory
<prefix>+dHorizontal split (top/bottom), opens in current pane’s directory
Both splits inherit #{pane_current_path} so the new pane always starts in the same directory you were working in.

​
Pane Navigation

vim-tmux-navigator maps the following globally (no prefix needed):
BindingAction
Ctrl+hMove to pane left (or Neovim split left)
Ctrl+jMove to pane down (or Neovim split down)
Ctrl+kMove to pane up (or Neovim split up)
Ctrl+lMove to pane right (or Neovim split right)

​
Session Management

BindingAction
<prefix>+KKill all sessions except the current one (prompts for confirmation)
M-g (Alt+g)Toggle the floating scratch session (see below)

​
Copy Mode

mode-keys vi enables Vim-style navigation in copy mode. The y key copies the selection to the clipboard:
  • Linux/WSL: y pipes to clip (Windows clipboard via WSL interop)
  • macOS: y pipes to pbcopy
The correct binding is chosen automatically at startup via if-shell 'uname | grep -q Darwin'.

​
Floating Scratch Session

M-g (Alt+g) toggles a floating popup scratch session — a persistent throwaway shell that appears over your current work and disappears when you detach from it. 
bind-key -n M-g if-shell -F '#{==:#{session_name},scratch}' {
    detach-client
} {
    display-popup -d "#{pane_current_path}" -E "tmux new-session -A -s scratch"
}
How it works:
  • If you are already inside the scratch session, M-g detaches you, closing the popup and returning to your previous session.
  • If you are in any other session, M-g opens a display-popup floating window rooted at the current pane’s working directory and attaches to (or creates) the scratch session.
The -A flag in tmux new-session -A -s scratch means “attach if it already exists” — so the scratch session is persistent across invocations and retains its history.

​
Other Settings

SettingValuePurpose
mouseonClick to focus panes/windows, scroll with wheel
status-positiontopStatus bar appears at the top of the terminal
base-index1Windows numbered from 1 instead of 0
pane-base-index1Panes numbered from 1 instead of 0
mode-keysviVim bindings in copy and choice modes
default-terminaltmux-256colorCorrect $TERM inside tmux sessions
terminal-overrides,xterm-256color:TcEnables true-color (24-bit) passthrough
extended-keysalwaysPasses extended key sequences (fixes Shift+Enter for opencode / Gemini CLI)
default-shell/home/linuxbrew/.linuxbrew/bin/zshUses the Homebrew-managed Zsh
default-command/home/linuxbrew/.linuxbrew/bin/zsh -lLaunches Zsh as a login shell

​
Complete Configuration File

# Carga TPM
set -g @plugin 'tmux-plugins/tpm'

# Opciones ya probadas que limpian problemas de TMUX
set -g @plugin 'tmux-plugins/tmux-sensible'

# Tmux Navigation
set -g @plugin 'christoomey/vim-tmux-navigator'

# Tmux Resurrect
set -g @plugin 'tmux-plugins/tmux-resurrect'

# Which Key
set -g @plugin 'alexwforsythe/tmux-which-key'

# Floating window
bind-key -n M-g if-shell -F '#{==:#{session_name},scratch}' {
detach-client
} {
# open in the same directory of the current pane
display-popup -d "#{pane_current_path}" -E "tmux new-session -A -s scratch"
}

# Tema Gruvbox
set -g @plugin 'egel/tmux-gruvbox'
set -g @gruvbox 'dark'   # opciones: 'dark' o 'light'



# Fix colors for the terminal
set -g default-terminal 'tmux-256color'
set -ga terminal-overrides ",xterm-256color:Tc"

# Modo vim
set -g mode-keys vi
if-shell 'uname | grep -q Darwin' 'bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"' 'bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "clip"'

# Keymaps
unbind C-b
set -g prefix C-a
bind C-a send-prefix

unbind %
unbind '"'
bind v split-window -h -c "#{pane_current_path}"
bind d split-window -v -c "#{pane_current_path}"

# Mouse support
set -g mouse on

# Status bar position
set -g status-position top

# Kill all sessions except current
bind K confirm-before -p "Kill all other sessions? (y/n)" "kill-session -a"

# Fix index
set -g base-index 1
setw -g pane-base-index 1

# Fix opencode and gemini cli shift + enter
set -g extended-keys always

# Homebrew zsh
set -g default-shell /home/linuxbrew/.linuxbrew/bin/zsh
set -g default-command "/home/linuxbrew/.linuxbrew/bin/zsh -l"


run -b '~/.tmux/plugins/tpm/tpm'

Build docs developers (and LLMs) love

Get started for freeTalk to us