iterm2

What this skill does

# Iterm2

Complete reference for iTerm2 terminal emulator and tmux terminal multiplexer on macOS. Covers keyboard shortcuts, configuration, tmux integration, and productivity workflows.

## Workflow Routing

**When executing a workflow, do BOTH of these:**

1. **Call the notification script** (for observability tracking):
   ```bash
   ~/.claude/Tools/SkillWorkflowNotification WORKFLOWNAME Iterm2
   ```

2. **Output the text notification** (for user visibility):
   ```
   Running the **WorkflowName** workflow from the **Iterm2** skill...
   ```

| Workflow | Trigger | File |
|----------|---------|------|
| **SetupTmux** | "setup tmux", "configure tmux" | `workflows/SetupTmux.md` |
| **TmuxSession** | "tmux session", "attach session", "detach" | `workflows/TmuxSession.md` |
| **TroubleshootTmux** | "tmux not working", "fix tmux" | `workflows/TroubleshootTmux.md` |

## Examples

**Example 1: Split terminal into multiple panes**
```
User: "How do I split my terminal in iTerm2?"
→ References Shortcuts.md
→ Explains Cmd+D (vertical) and Cmd+Shift+D (horizontal)
→ Shows navigation with Cmd+Option+Arrow
```

**Example 2: Setup tmux with iTerm2 integration**
```
User: "How do I use tmux with iTerm2?"
→ Invokes SetupTmux workflow
→ Explains tmux -CC control mode
→ Shows native window integration benefits
```

**Example 3: Manage persistent sessions over SSH**
```
User: "Keep my terminal running after disconnect"
→ Invokes TmuxSession workflow
→ Creates named session with tmux new -s
→ Shows how to reattach after disconnect
```

## Quick Reference

### iTerm2 Essentials

| Action | Shortcut |
|--------|----------|
| Split Vertical | `Cmd+D` |
| Split Horizontal | `Cmd+Shift+D` |
| Navigate Panes | `Cmd+Option+Arrow` |
| Maximize Pane | `Cmd+Shift+Enter` |
| Next/Prev Tab | `Cmd+{` / `Cmd+}` |
| Find | `Cmd+F` |
| Autocomplete | `Cmd+;` |
| Paste History | `Cmd+Shift+H` |
| Instant Replay | `Cmd+Option+B` |
| Find Cursor | `Cmd+/` |

### tmux Essentials

Default prefix: `Ctrl+b`

| Action | Shortcut |
|--------|----------|
| New Session | `tmux new -s name` |
| List Sessions | `tmux ls` or `Ctrl+b s` |
| Attach Session | `tmux attach -t name` |
| Detach | `Ctrl+b d` |
| New Window | `Ctrl+b c` |
| Split Vertical | `Ctrl+b %` |
| Split Horizontal | `Ctrl+b "` |
| Navigate Panes | `Ctrl+b Arrow` |
| Zoom Pane | `Ctrl+b z` |
| Close Pane | `Ctrl+b x` |
| Copy Mode | `Ctrl+b [` |

### iTerm2 + tmux Integration

Run `tmux -CC` for native iTerm2 integration:
- tmux windows appear as native iTerm2 windows
- Use iTerm2 shortcuts instead of tmux prefix
- Sessions persist through disconnects
- Dashboard available via Shell > tmux > Dashboard

## Documentation Index

| Document | Purpose |
|----------|---------|
| `Shortcuts.md` | Complete keyboard shortcut reference |
| `TmuxConfig.md` | tmux configuration (.tmux.conf) guide |
| `TmuxCommands.md` | Full tmux command reference |

---

## Gotchas

- **"Reuse previous session's directory" is per-profile and per-context:** New windows from Cmd-N use the profile's window setting; new tabs from Cmd-T use the tab setting. They differ — confusing when prompts open in unexpected directories.
- **`tmux -CC` requires the tmux server to be installed and started:** If tmux is on a remote host but iTerm2 is local, `tmux -CC attach` works over SSH only when SSH was started from iTerm2 itself — not from a script that spawns a subshell.
- **Cmd-D split uses the current pane's profile, NOT the window default:** Once a profile changes mid-session (via shell integration), new splits inherit the modified profile and can carry unwanted env or PATH.
- **`Ctrl+b` prefix conflicts with readline `transpose-words`:** Vi-mode users who rebind it (`set -g prefix C-a`) must remember `Ctrl+a` also conflicts with screen and shell line-start — pick a free combo like `C-Space`.
- **Shell integration injects OSC 1337 escape codes:** Pipelines that capture terminal output (script, asciinema) end up with garbled control sequences unless integration is disabled per-pane via `Edit Session > Disable Shell Integration`.
- **Status bar updates run on the main thread:** Heavy custom status bar scripts (long `git status`, slow cloud CLIs) freeze the entire terminal — keep status callbacks under 100ms or run them async.