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.