Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shawal-mbalire/dotfiles/llms.txt

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

​
Overview

This tmux configuration features the Catppuccin Mocha theme with transparent backgrounds, VI keybindings, and powerful plugins for session management, floating windows, and fuzzy finding.

​
Configuration Structure

The configuration merges multiple concerns into a single file:
  • opts.conf - General tmux options
  • keybinds.conf - Key bindings
  • skin.conf - Catppuccin theme settings
  • plugins.conf - Plugin declarations and configuration
Location: ~/.config/tmux/tmux.conf

​
General Options

​
Terminal Settings

set-option -g default-terminal 'screen-256color'
set-option -g terminal-overrides ',xterm-256color:RGB'
set -g default-terminal "${TERM}"
Ensures proper color support and uses your existing $TERM value.

​
Base Settings

set -g base-index 1              # Windows start at 1
set -g pane-base-index 1         # Panes start at 1
set -g detach-on-destroy off     # Don't exit when closing session
set -g escape-time 0             # No escape delay
set -g history-limit 1000000     # 1M lines of history
set -g renumber-windows on       # Renumber on window close
set -g status-position top       # Status bar at top

​
Input and Interaction

set -g mode-keys vi              # VI keys in copy mode
set -g mouse on                  # Enable mouse support
set -g set-clipboard on          # Use system clipboard

​
Border Colors

set -g pane-active-border-style 'fg=magenta,bg=default'
set -g pane-border-style 'fg=brightblack,bg=default'

​
Key Bindings

​
Prefix Key

set -g prefix C-Space
Prefix: Ctrl+Space (instead of default Ctrl+b)

​
Copy Mode (VI)

bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi C-v send-keys -X rectangle-toggle
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel
KeyAction
vBegin selection
Ctrl+VToggle rectangular selection
yCopy and exit copy mode

​
Window Splitting

bind '"' split-window -v -c "#{pane_current_path}"
bind % split-window -h -c "#{pane_current_path}"
Splits open in the current pane’s directory.
KeyAction
Prefix + "Split horizontally
Prefix + %Split vertically

​
Essential Commands

KeyAction
Prefix + cNew window
Prefix + ,Rename window
Prefix + &Kill window
Prefix + xKill pane
Prefix + dDetach session
Prefix + [Enter copy mode
Prefix + ]Paste buffer

​
Plugins

​
Core Plugins

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-yank'
set -g @plugin 'christoomey/vim-tmux-navigator'
set -g @plugin 'shawal-mbalire/catppuccin-tmux'
set -g @plugin 'tmux-plugins/tmux-battery'

​
Vim-Tmux Navigator

Seamless navigation between vim and tmux panes:
KeyAction
Ctrl+HMove left
Ctrl+JMove down
Ctrl+KMove up
Ctrl+LMove right
Works in both Vim/Neovim and tmux panes.

​
SessionX

Powerful session manager with zoxide integration: 
set -g @plugin 'omerxx/tmux-sessionx'
set -g @sessionx-bind 'o'
set -g @sessionx-window-height '85%'
set -g @sessionx-window-width '75%'
set -g @sessionx-zoxide-mode 'on'
set -g @sessionx-auto-accept 'off'
set -g @sessionx-filter-current 'false'
Launch: Prefix + o Features:
  • Fuzzy find sessions
  • Create new sessions from zoxide directories
  • Preview session contents
  • Switch or create sessions instantly

​
Floax

Floating terminal windows: 
set -g @plugin 'omerxx/tmux-floax'
set -g @floax-bind 'p'
set -g @floax-width '80%'
set -g @floax-height '80%'
set -g @floax-border-color 'magenta'
set -g @floax-text-color 'blue'
set -g @floax-change-path 'true'
Launch: Prefix + p Opens a floating terminal window (80% of screen size).

​
FZF Integrations

set -g @plugin 'sainnhe/tmux-fzf'
Fuzzy find tmux sessions, windows, and panes.Launch: Prefix + F (default)

​
Battery Indicator

set -g @plugin 'tmux-plugins/tmux-battery'
Displays battery status in the status bar (configured in theme).

​
Catppuccin Theme

​
Theme Configuration

set -g @catppuccin_flavour 'mocha'
set -g @catppuccin_status_background "default"
Mocha flavor with transparent background.

​
Window Status Format

set -g @catppuccin_window_left_separator ""
set -g @catppuccin_window_right_separator ""
set -g @catppuccin_window_middle_separator "█"
set -g @catppuccin_window_number_position "right"

set -g @catppuccin_window_default_fill "number"
set -g @catppuccin_window_default_text "#W"
set -g @catppuccin_window_current_fill "number"
set -g @catppuccin_window_current_text "#{pane_current_path}"
  • Default windows show window name
  • Current window shows current directory path

​
Status Modules

set -g @catppuccin_status_modules_right "application date_time battery"
set -g @catppuccin_status_modules_left "session"
set -g @catppuccin_status_modules_middle "host"
Layout: [session] ... [host] ... [app] [time] [battery]

​
Status Separators

set -g @catppuccin_status_left_separator ""
set -g @catppuccin_status_right_separator ""
set -g @catppuccin_status_fill "icon"
set -g @catppuccin_status_connect_separator "no"
Powerline-style separators with icon filling.

​
Custom Modules

set -g @catppuccin_directory_text "#{b:pane_current_path}"
set -g @catppuccin_date_time_text "%H:%M"
set -g @catppuccin_date_time_icon "󰃰"
set -g @catppuccin_date_time_color "$thm_blue"

​
Transparent Background

set -g status-bg default
set -g status-style bg=default
Forces transparent status bar background.

​
Extra Spacing

set -g status-format[2] " "
Adds blank row below status bar for breathing room.

​
Plugin Installation

​
First-Time Setup

  1. Install TPM (Tmux Plugin Manager):
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
  1. Reload tmux config:
tmux source ~/.config/tmux/tmux.conf
  1. Install plugins:
Inside tmux: Prefix + I (capital I)

​
Managing Plugins

KeyAction
Prefix + IInstall new plugins
Prefix + UUpdate plugins
Prefix + alt + uUninstall removed plugins

​
Local Configuration

Custom settings without modifying the main config: 
if-shell "[ -f ~/.config/tmux/tmux.local.conf ]" 'source ~/.config/tmux/tmux.local.conf'
Create ~/.config/tmux/tmux.local.conf for machine-specific overrides. Example: 
# ~/.config/tmux/tmux.local.conf
set -g @catppuccin_status_modules_right "application date_time cpu battery"

​
Usage Tips

​
Creating Sessions

# Named session
tmux new -s myproject

# Session in directory
tmux new -s work -c ~/projects/work

​
Attaching to Sessions

# Attach to last session
tmux attach

# Attach to named session
tmux attach -t myproject

# Kill session
tmux kill-session -t myproject

​
Using SessionX

  1. Press Prefix + o
  2. Fuzzy search sessions or directories
  3. Press Enter to switch or Ctrl+X to create new
With zoxide integration, frequently used directories appear first.

​
Floating Terminal (Floax)

  1. Press Prefix + p
  2. A floating window opens
  3. Press Prefix + p again to toggle
Perfect for quick commands without leaving your workspace.

​
FAQ

Ensure TPM is installed:
ls ~/.config/tmux/plugins/tpm
If missing:
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
Then reload and install: Prefix + I
Check terminal $TERM value:
echo $TERM
Should be xterm-256color or similar. Set in your shell profile:
set -gx TERM xterm-256color
Inside tmux:
Prefix + :source ~/.config/tmux/tmux.conf
Or from shell:
tmux source ~/.config/tmux/tmux.conf
Ensure mouse mode is enabled:
set -g mouse on
Reload config: Prefix + :source ~/.config/tmux/tmux.conf
Modify Catppuccin module settings:
set -g @catppuccin_status_modules_right "cpu memory battery date_time"
See Catppuccin Tmux docs for available modules.

​
Configuration Location

~/.config/tmux/
├── tmux.conf
├── tmux.local.conf (optional)
└── plugins/
    └── tpm/
  • See Neovim for editor integration
  • See Fish Shell for shell configuration
  • See Kitty for terminal settings

Build docs developers (and LLMs) love

Get started for freeTalk to us