← Back to articles

tmux Configuration with chezmoi

Path: Computer Tech/Terminal/tmux/tmux Configuration with chezmoi.mdUpdated: 2/3/2026

tmux Configuration with chezmoi

This guide shows you how to manage your tmux configuration with chezmoi, making your tmux setup portable across all your machines.

Series navigation:

  1. tmux Basics - Core concepts
  2. tmux Configuration with chezmoi (this article)
  3. TPM - Tmux Plugin Manager - Plugins
  4. Ghostty + tmux Startup Automation - Startup workflows
  5. tmux Session Presets - Project layouts

What Problem Does This Solve?

Without chezmoi:

  • Copy .tmux.conf manually between machines
  • Forget which machine has the latest config
  • No version control for your tmux settings
  • TPM plugins may be out of sync

With chezmoi:

  • One source of truth for all configs
  • Changes sync across machines instantly
  • Full Git history of your configuration
  • Automated setup on new machines

Pre-Setup Checklist

βœ… chezmoi installed (brew install chezmoi) βœ… chezmoi initialized (chezmoi init) βœ… tmux installed (brew install tmux)

See chezmoi for complete chezmoi setup.

Basic Workflow: Adding Your tmux Config

Step 1: Add Your Config to chezmoi

If you already have a .tmux.conf:

bash
# Add your existing config to chezmoi
chezmoi add ~/.tmux.conf

# Edit it through chezmoi (optional)
chezmoi edit ~/.tmux.conf

# Apply changes
chezmoi apply

If you don't have a config yet, create one through chezmoi:

bash
# Create new tmux config
chezmoi edit ~/.tmux.conf
# (Opens your editor with a new file)

# Apply it
chezmoi apply

Step 2: Verify It's Managed

bash
# Check that chezmoi is managing the file
chezmoi managed | grep tmux.conf

# See the difference between source and target
chezmoi diff

Step 3: Commit to Git

bash
# Navigate to chezmoi source directory
cd ~/.local/share/chezmoi

# Commit your changes
git add .
git commit -m "Add tmux configuration"
git push

Managing TPM with Homebrew + Brewfile

Recommended approach: Install TPM via Homebrew and track it in your Brewfile.

Step 1: Install TPM via Homebrew

bash
brew install tmux tpm

Step 2: Add to Your Brewfile

bash
# Regenerate Brewfile to include tmux and tpm
brew bundle dump --file=~/Brewfile --force

# Add Brewfile to chezmoi
chezmoi add ~/Brewfile

Step 3: Tell chezmoi to Ignore Plugin Directory

bash
# Add to ~/.local/share/chezmoi/.chezmoiignore
echo ".tmux/plugins/*" >> ~/.local/share/chezmoi/.chezmoiignore

This prevents chezmoi from trying to manage the actual plugin files (installed by TPM).

Step 4: Update tmux.conf for Homebrew TPM

When TPM is installed via Homebrew, the path is different. Update your .tmux.conf:

bash
# Change from:
run '~/.tmux/plugins/tpm/tpm'

# To (for Homebrew):
run '/opt/homebrew/opt/tpm/share/tpm/tpm'

Alternative: Create a symlink for compatibility:

bash
mkdir -p ~/.tmux/plugins
ln -s /opt/homebrew/opt/tpm/share/tpm ~/.tmux/plugins/tpm

Then you can keep using the standard path in .tmux.conf.

On New Machines

bash
# 1. Install Homebrew packages (including tmux and tpm)
brew bundle install --file=~/Brewfile

# 2. Apply chezmoi configs
chezmoi init
chezmoi apply

# 3. Inside tmux, install plugins
tmux
Ctrl+B I  # Install plugins

Why this approach is better:

  • βœ… TPM updates via brew upgrade like other tools
  • βœ… Version controlled in Brewfile
  • βœ… No need for custom install scripts
  • βœ… Works seamlessly with your package management workflow

See Managing Homebrew with Brewfile for full Brewfile workflow.

Step 3: Document Plugin Installation

In your .tmux.conf (managed by chezmoi), add this comment at the top:

bash
# ============================================
# Plugins (Managed by TPM)
# ============================================
# After applying this config:
# 1. Start tmux
# 2. Press Ctrl+B I to install plugins
# ============================================

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'

# Initialize TPM (keep at bottom)
run '~/.tmux/plugins/tpm/tpm'

Workflow: Updating Config Across Machines

On Machine A (where you make changes):

bash
# Edit config
chezmoi edit ~/.tmux.conf

# Apply changes locally
chezmoi apply

# Test in tmux
tmux source ~/.tmux.conf

# If good, commit
cd ~/.local/share/chezmoi
git add .
git commit -m "Update tmux: added vim-style navigation"
git push

On Machine B (pull changes):

bash
# Pull latest changes
chezmoi update

# Reload tmux config
tmux source ~/.tmux.conf

That's it! Your config is synced.

Advanced: Template Variables

You can make your tmux config adapt to different machines using chezmoi templates.

Example: Different status bar colors per machine.

Step 1: Add Variables to chezmoi Config

Edit ~/.config/chezmoi/chezmoi.toml:

toml
[data]
    hostname = "{{ .chezmoi.hostname }}"
    [data.tmux]
        status_bg = "colour234"  # Default

Create machine-specific overrides:

bash
# On your desktop
chezmoi edit ~/.config/chezmoi/chezmoi.toml --apply

Add:

toml
[data.tmux]
    status_bg = "colour22"  # Green for desktop

On your laptop:

toml
[data.tmux]
    status_bg = "colour17"  # Blue for laptop

Step 2: Use Templates in .tmux.conf

Rename your config to use templating:

bash
# Tell chezmoi this file is a template
mv ~/.local/share/chezmoi/dot_tmux.conf ~/.local/share/chezmoi/dot_tmux.conf.tmpl

Edit it:

bash
chezmoi edit ~/.tmux.conf

Use the variable:

bash
# Status bar (color varies by machine)
set -g status-bg {{ .tmux.status_bg }}

Apply:

bash
chezmoi apply

Now each machine gets a different status bar color automatically!

Recommended Starter Config

Here's a solid starter .tmux.conf to manage with chezmoi:

bash
# ============================================
# Basic Settings
# ============================================

# Change prefix to Ctrl+A (more ergonomic)
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Enable mouse support
set -g mouse on

# Start windows and panes at 1, not 0
set -g base-index 1
setw -g pane-base-index 1

# Renumber windows when one is closed
set -g renumber-windows on

# Enable 256 colors
set -g default-terminal "screen-256color"

# Increase scrollback buffer
set -g history-limit 50000

# ============================================
# Better Keybindings
# ============================================

# Split panes using | and -
bind | split-window -h
bind - split-window -v
unbind '"'
unbind %

# Reload config
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# Vim-like pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Vim-like copy mode
setw -g mode-keys vi
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-selection-and-cancel

# ============================================
# Status Bar
# ============================================

set -g status-position bottom
set -g status-bg colour234
set -g status-fg colour137
set -g status-left '#[fg=colour233,bg=colour245,bold] #S '
set -g status-right '#[fg=colour233,bg=colour245,bold] %Y-%m-%d %H:%M '

# ============================================
# Plugins (Managed by TPM)
# After applying: Press Ctrl+B I to install
# ============================================

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

# Auto-restore sessions
set -g @continuum-restore 'on'

# Initialize TPM (keep at bottom)
run '~/.tmux/plugins/tpm/tpm'

Save this as your ~/.tmux.conf and add it to chezmoi!

Troubleshooting

Config not syncing

bash
# Check if file is managed
chezmoi managed | grep tmux.conf

# Force apply
chezmoi apply --force

TPM not installing plugins

bash
# Manually clone TPM
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Inside tmux, install plugins
Ctrl+B I

Changes not taking effect

bash
# Reload tmux config
tmux source ~/.tmux.conf

# Or restart tmux server
tmux kill-server
tmux

Next Steps

Related: