julianobarbosa/iterm2

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):

   ~/.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.