iterm2-layout

# iTerm2 Layout Configuration

<!-- ADR: /docs/adr/2025-12-15-iterm2-layout-config.md -->

Configure iTerm2 workspace layouts with proper separation of concerns: private paths in TOML config, publishable code in Python script.

## Triggers

Invoke this skill when user mentions:

- "iTerm2 layout"
- "workspace tabs"
- "layout.toml"
- "AutoLaunch script"
- "default-layout.py"
- "configure terminal workspaces"
- "add workspace tab"

## Configuration Overview

### File Locations

| File             | Location                               | Purpose                |
| ---------------- | -------------------------------------- | ---------------------- |
| Config (private) | `~/.config/iterm2/layout.toml`         | User's workspace paths |
| Script (public)  | `~/scripts/iterm2/default-layout.py`   | Layout logic           |
| Template         | `~/scripts/iterm2/layout.example.toml` | Example config         |

### Config File Format

```toml
# ~/.config/iterm2/layout.toml

[layout]
left_pane_ratio = 0.20    # 0.0 to 1.0
settle_time = 0.3         # seconds

[commands]
left = "br --sort-by-type-dirs-first"
right = "zsh"

[worktrees]
# Optional: Enable git worktree discovery
# main_repo_root = "~/projects/my-project"
# worktree_pattern = "my-project.worktree-*"

[[tabs]]
name = "home"
dir = "~"

[[tabs]]
name = "projects"
dir = "~/projects"

[[tabs]]
dir = "~/Documents"  # name defaults to "Documents"
```

## Setup Instructions

### First-Time Setup

```bash
/usr/bin/env bash << 'CONFIG_EOF'
# 1. Ensure config directory exists
mkdir -p ~/.config/iterm2

# 2. Copy template
cp ~/scripts/iterm2/layout.example.toml ~/.config/iterm2/layout.toml

# 3. Edit with your workspace paths
# Add [[tabs]] entries for each workspace

# 4. Restart iTerm2 to test
CONFIG_EOF
```

### Adding a New Tab

Add a `[[tabs]]` entry to `~/.config/iterm2/layout.toml`:

```toml
[[tabs]]
name = "MyProject"  # Tab display name (optional)
dir = "~/path/to/project"
```

**Name field**:

- If omitted, uses dir