julianobarbosa/claude-code-skills/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):

``bash ~/.claude/Tools/SkillWorkflowNotification WORKFLOWNAME Iterm2 ``

1. Output the text notification (for user visibility):

`` Running the **WorkflowName** workflow from the **Iterm2** skill... ``

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

tmux Essentials

Default prefix: 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

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.