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 Iterm2

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.

iterm2