# Tmuxifier Session Templates

This directory contains reusable tmux session and window layouts managed by [tmuxifier](https://github.com/jimeh/tmuxifier).

## Installation

### 1. Install tmuxifier

```bash
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:

```fish
source ~/.config/fish/config.fish
```

### 4. Verify installation

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

tmuxifier help
# Should show tmuxifier commands
```

## Quick Start

After installing tmuxifier, create and load sessions:

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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
# 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):

```bash
# 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

```bash
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