julianobarbosa 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:
Call the notification script (for observability tracking):
~/.claude/Tools/SkillWorkflowNotification WORKFLOWNAME Iterm2Output 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 -CCrequires the tmux server to be installed and started: If tmux is on a remote host but iTerm2 is local,tmux -CC attachworks 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+bprefix conflicts with readlinetranspose-words: Vi-mode users who rebind it (set -g prefix C-a) must rememberCtrl+aalso conflicts with screen and shell line-start — pick a free combo likeC-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.