tmux-layouts

May 17, 2026 ยท View on GitHub

A tmux plugin for managing session layouts.

Installation

  1. Add to your ~/.tmux.conf:
set -g @plugin 'juancruzfl/tmux-layouts'

  1. Press prefix + I to install

  2. Reload tmux config:

tmux source-file ~/.tmux.conf

Manual Installation

  1. Clone the repository:
git clone https://github.com/juancruzfl/tmux-layouts ~/.tmux/plugins/tmux-layouts
  1. Add to your ~/.tmux.conf:
run-shell ~/.tmux/plugins/tmux-layouts/tmux-layouts.tmux
  1. Reload tmux config:
tmux source-file ~/.tmux.conf

Verify Installation

Check that the hook is registered:

tmux show-hooks -g | grep after-new-session

Should output:

after-new-session  run-shell '/path/to/tmux-layouts/scripts/session-init.sh #{session_name}'

Usage

Creating Session layouts

Create a session layout:

tmux new -s dev

The plugin will:

  • Look for a predefined layout at ~/.tmux/plugins/tmux-layouts/layouts/dev.sh
  • Or look for a saved layout at ~/.tmux-layouts/dev.sh
  • Or create a new default layout if neither exists

Saving Your Current Layout

Save your current session layout:

# Press: prefix + Shift+S (hold Shift and press S)

Note: Lowercase s (prefix + s) is tmux's built-in session tree viewer and is NOT used by this plugin. Your layout will be saved to ~/.tmux-layouts/<session-name>.sh

Custom Keybindings

Customize the save keybinding in your ~/.tmux.conf:

# Use a different key
unbind S
bind-key C run-shell "bash ~/.tmux/plugins/tmux-layouts/scripts/layout-state.sh"

# Or use without prefix (just Ctrl+s)
bind-key -n C-s run-shell "bash ~/.tmux/plugins/tmux-layouts/scripts/layout-state.sh"

Creating Custom Layouts

Create predefined layouts in ~/.tmux/plugins/tmux-layouts/layouts/:

#!/usr/bin/env bash
# Layout: dev
# Development environment

# Window 1: Code editor
tmux rename-window -t "$SESSION_NAME:0" "editor"
tmux send-keys -t "$SESSION_NAME:0" "nvim ." C-m

tmux split-window -t "$SESSION_NAME:0" -h -p 30
tmux send-keys -t "$SESSION_NAME:0.1" "git status" C-m

# Window 2: Servers
tmux new-window -t "$SESSION_NAME" -n "servers"
tmux send-keys -t "$SESSION_NAME:servers" "npm run dev" C-m

# Return to editor
tmux select-window -t "$SESSION_NAME:0"

Save this as ~/.tmux/plugins/tmux-layouts/layouts/dev.sh and make it executable:

chmod +x ~/.tmux/plugins/tmux-layouts/layouts/dev.sh

Now tmux new -s dev will automatically load this layout!

Development

Setting Up a Test Environment

To test the plugin without affecting your main tmux configuration, use the included sandbox environment:

  1. Clone the repository:
git clone https://github.com/juancruzfl/tmux-layouts ~/projects/tmux-layouts
cd ~/projects/tmux-layouts
  1. Start a sandbox tmux session:
tmux -L sandbox -f test/test.conf new-session -s "plugin-test"

The -L sandbox flag creates an isolated tmux server that won't interfere with your main tmux sessions. Ensure the paths in the test.conf file keybindings match your current testing enviroment.

Test Configuration Features

The test/test.conf file provides:

  • Visual indicators: Yellow status bar shows you're in TEST MODE
  • Debug keybindings:
    • prefix + H - Show registered hooks
    • prefix + M - Show tmux messages
    • prefix + D - Show debug log
    • prefix + r - Reload test config
  • Quick test layouts:
    • prefix + 1 - Create simple 2-pane layout
    • prefix + 2 - Create 3-pane layout
    • prefix + 3 - Create 4-pane layout

Manual Testing Workflow

# 1. Start sandbox session
tmux -L sandbox -f test/test.conf new-session -s "my-test"

# 2. Inside the session:
#    - Press prefix + 1 to create a test layout
#    - Press prefix + Shift+S to save the layout
#    - Press prefix + L to list saved layouts
#    - Press prefix + H to verify hooks

# 3. Test layout restoration
#    - Exit the session (type 'exit' or press Ctrl+d)
#    - Recreate it: tmux -L sandbox -f test/test.conf new-session -s "my-test"
#    - Your layout should be restored!

# 4. Clean up when done
tmux -L sandbox kill-server
rm -rf ~/.tmux-layouts-test

Testing Different Layouts

The test environment includes example layouts in layouts/:

# Test the dev layout
tmux -L sandbox -f test/test.conf new-session -s "dev"

# Test the simple layout
tmux -L sandbox -f test/test.conf new-session -s "simple"

Troubleshooting

Layouts aren't loading

  1. Check hook is set:
tmux show-hooks -g | grep after-new-session
  1. Verify permissions:
ls -la ~/.tmux/plugins/tmux-layouts/tmux-layouts.tmux
# Should show: -rwxr-xr-x (executable)
  1. Check tmux messages for errors:
tmux show-messages
  1. Manually test the init script:
bash -x ~/.tmux/plugins/tmux-layouts/scripts/session-init.sh dev

Layout save returns error 127

This means the script file can't be found. Check:

ls -la ~/.tmux/plugins/tmux-layouts/scripts/layout-state.sh
# Verify the file exists and is executable

chmod +x ~/.tmux/plugins/tmux-layouts/scripts/layout-state.sh
# Make it executable if needed

Wrong keybinding triggered

If pressing prefix + s shows the session tree instead of saving:

  • You're using lowercase s instead of Shift+S
  • Press prefix then hold Shift and press S

Test environment conflicts with main tmux

The test environment uses -L sandbox to create a separate tmux server. If you're having issues:

# Kill the sandbox server
tmux -L sandbox kill-server

# Your main tmux sessions are unaffected
tmux ls  # Shows your normal sessions

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Test your changes using the sandbox environment:
   tmux -L sandbox -f test/test.conf new-session -s "test-feature"
  1. Submit a pull request