work/term/.config/tmux/README.md

Tmuxifier Session Templates

This directory contains reusable tmux session and window layouts managed by tmuxifier.

Installation

1. Install tmuxifier

git clone https://github.com/jimeh/tmuxifier.git ~/.tmuxifier

2. Add to tmux (via TPM)

The tmux.conf in this directory already includes the tmuxifier plugin. After starting tmux, press prefix + I to install it via TPM.

3. Add to your shell

The fish config (~/.config/fish/config.fish) in this repo already includes tmuxifier initialization. Restart fish or run:

source ~/.config/fish/config.fish

4. Verify installation

which tmuxifier
# Should output: ~/.tmuxifier/bin/tmuxifier

tmuxifier help
# Should show tmuxifier commands

Quick Start

After installing tmuxifier, create and load sessions:

# Create a new session layout
tmuxifier new-session my-project

# Load a session
tmuxifier load-session my-project    # or: t s my-project

# Edit an existing session
tmuxifier edit-session my-project    # or: t es my-project

# Create a window layout (for use within existing sessions)
tmuxifier new-window my-window
tmuxifier load-window my-window      # or: t lw my-window

Directory Structure

tmuxifier/
├── layouts/
│   ├── *.session.sh   # Full session definitions
│   └── *.window.sh    # Window-only definitions

Session Template Reference

Basic Structure

# Set a custom session root path (must be called before initialize_session)
session_root "~/projects/my-project"

# Create session with specified name if it does not already exist
if initialize_session "my-project"; then

  # Create windows
  new_window "editor"
  new_window "server"
  new_window "logs"

  # Select the default active window
  select_window "editor"

  # Run commands in the selected window
  run_cmd "cd ~/projects/my-project"

  # Send keys (like typing) to the pane
  send_keys "nvim ." C-m

  # Finalize session creation and switch/attach to it
  finalize_and_go_to_session
fi

Commands Reference

Session Commands

Command	Description
session_root "path"	Set root directory for session (must be first)
initialize_session "name"	Create session if it doesn't exist
finalize_and_go_to_session	Complete creation and attach to session
select_window "name"	Set active window

Window Commands

Command	Description
new_window "name"	Create a new window
select_window "name"	Switch to existing window
run_cmd "command"	Execute command in current pane
send_keys "keys"	Send key sequence to pane
send_text "text"	Send raw text to pane
split_h [percent]	Horizontal split (default 50%)
split_v [percent]	Vertical split (default 50%)
select_pane [target]	Select pane (up, down, left, right, left-or-up, right-or-down)

Pane Target Options

For select_pane:

• up, down, left, right - Navigate to adjacent pane
• left-or-up, right-or-down - Prefer first direction, fall back to second

Key Modifiers

Symbol	Meaning
C-m	Enter/Return key
C-c	Ctrl+C
C-d	Ctrl+D (EOF)
M-m	Alt/Meta+m
C-\\	Ctrl+\

Example Templates

Understanding the pane system is key. Here's a visual breakdown:

┌─────────────────────────────────────────────────────┐
│ Window: "editor"                                    │
│ ┌─────────────────────┬───────────────────────────┐ │
│ │ Pane 1 (40%)        │ Pane 2 (60%)             │ │
│ │ nvim                │ npm run dev              │ │
│ │                     ├───────────────────────────┤ │
│ │                     │ Pane 3 (50% of pane 2)  │ │
│ │                     │ npm run test             │ │
│ └─────────────────────┴───────────────────────────┘ │
└─────────────────────────────────────────────────────┘

Example 1: Two Panes Side by Side

session_root "~/projects/app"

if initialize_session "app"; then
  new_window "editor"

  # Split horizontally (40% left, 60% right)
  split_h 40

  # Run command in first pane (left side)
  run_cmd "cd ~/projects/app && nvim"

  # Move to second pane (right side) and split vertically
  select_pane right
  split_v 50

  # Run commands in the new panes
  run_cmd "npm run dev"
  select_pane right
  run_cmd "npm run test"

  select_window "editor"
  finalize_and_go_to_session
fi

Example 2: Three Panes with Nested Split

session_root "~/projects/app"

if initialize_session "app"; then
  new_window "editor"

  # Create three panes: top (20%), bottom-left (40%), bottom-right (40%)
  split_v 20        # horizontal split at 20%
  run_cmd "htop"    # top pane: system monitor

  select_pane down  # move to bottom
  split_h 50        # vertical split bottom into left/right
  run_cmd "npm run dev"   # bottom-left
  select_pane right
  run_cmd "npm run test"  # bottom-right

  select_window "editor"
  finalize_and_go_to_session
fi

Resulting layout:
┌─────────────────────────────────────┐
│           htop (20%)                │
├──────────────┬──────────────────────┤
│ npm run dev │    npm run test      │
│   (40%)     │       (40%)          │
└──────────────┴──────────────────────┘

Example 3: Multiple Windows with Panes

session_root "~/projects/webapp"

if initialize_session "webapp"; then
  # Window 1: Main workspace with panes
  new_window "editor"
  split_h 50
  run_cmd "cd ~/projects/webapp && nvim"
  select_pane right
  run_cmd "cd ~/projects/webapp && npm run dev"

  # Window 2: Server with logs
  new_window "server"
  split_v 30
  run_cmd "cd ~/projects/webapp && python -m http.server 8000"
  select_pane right
  run_cmd "cd ~/projects/webapp && tail -f logs/app.log"

  # Window 3: Database
  new_window "database"
  run_cmd "docker compose up db"

  # Start on editor window
  select_window "editor"
  finalize_and_go_to_session
fi

Example 4: Practical Development Setup

session_root "~/projects/api"

if initialize_session "api"; then
  new_window "code"
  split_h 60
  run_cmd "cd ~/projects/api && nvim"
  select_pane right
  split_v 50
  run_cmd "cd ~/projects/api && uvicorn main:app --reload"
  select_pane right
  run_cmd "cd ~/projects/api && tail -f logs/api.log"

  new_window "tests"
  split_h 50
  run_cmd "cd ~/projects/api && pytest -v"
  select_pane right
  run_cmd "cd ~/projects/api && pytest --cov"

  new_window "shell"
  run_cmd "cd ~/projects/api"

  select_window "code"
  finalize_and_go_to_session
fi

Example 5: Simple Window Layout (No Panes)

session_root "~/projects/webapp"

if initialize_session "webapp"; then
  # Each window has a single pane
  new_window "editor"
  run_cmd "cd ~/projects/webapp && nvim"

  new_window "server"
  run_cmd "cd ~/projects/webapp && npm run dev"

  new_window "database"
  run_cmd "docker compose up db"

  new_window "logs"
  run_cmd "cd ~/projects/webapp && tail -f logs/app.log"

  select_window "editor"
  finalize_and_go_to_session
fi

Shell Integration

Aliases

Add these to your shell config for convenience:

# Bash/Zsh (.bashrc or .zshrc)
alias t='tmuxifier'
alias ts='tmuxifier load-session'
alias tes='tmuxifier edit-session'
alias tns='tmuxifier new-session'
alias tlw='tmuxifier load-window'

# Fish (.config/fish/config.fish or conf.d/)
alias t 'tmuxifier'
alias ts 'tmuxifier load-session'
alias tes 'tmuxifier edit-session'

Usage Without Tmux Prefix

If you want to load sessions from outside tmux (in a regular terminal):

# Run this in a plain terminal, NOT inside tmux
tmuxifier load-session my-project

Tips

1. Exit before loading: Make sure you're not inside tmux when running load-session
2. Auto-starting services: Use run_cmd with background processes (&) for long-running services
3. Docker containers: Commands like docker compose up -d work well in dedicated windows
4. Custom layouts path: Set TMUXIFIER_LAYOUT_PATH to use a different directory

export TMUXIFIER_LAYOUT_PATH="$HOME/.config/tmux/layouts"

Troubleshooting

"unknown command" when running tmuxifier?

• tmuxifier is not installed. Run: git clone https://github.com/jimeh/tmuxifier.git ~/.tmuxifier
• Restart your shell: source ~/.config/fish/config.fish
• Verify: which tmuxifier

Session won't load?

• Make sure you're NOT inside tmux when running load-session
• Make sure tmuxifier is initialized in your shell config
• Check that you have tmux installed: tmux -V
• Verify the layout file exists: ls ~/.tmuxifier/layouts/

TPM plugin not working?

• Inside tmux, press prefix + I (capital I) to install plugins
• prefix is Ctrl+Space by default in this config

Commands not running?

• Use run_cmd for single commands, not send_keys
• For interactive commands, consider using send_keys instead