it2

name	it2
description	Control iTerm2 terminals. Use when splitting panes, sending commands to sessions, checking session output, setting badges, creating layouts, or coordinating multiple terminals.
allowed-tools	["Bash","Read"]

it2 - iTerm2 CLI Automation

Essential Commands

# List sessions
it2 session list

# Get current session ID
echo $ITERM_SESSION_ID

# Split pane (-q returns new session ID)
NEW=$(it2 session split --horizontal -q)  # pane below
NEW=$(it2 session split --vertical -q)    # pane right

# Send command to session
it2 session send-text "$SID" "your command here"

# Read session content
it2 session get-screen "$SID"           # visible screen
it2 session get-buffer "$SID" --lines 50  # scrollback

# Set badge (always include session ID prefix)
it2 session set-badge "$SID" "$(echo $SID | cut -c1-8)\nLabel"

Discovering Sessions

# List all sessions
it2 session list

# With JSON for scripting
it2 session list --format=json | jq -r '.[] | "\(.session_id[:8]) \(.cwd)"'

Before Sending Commands

1. Check target session state first: it2 session get-screen "$SID"
2. Verify it's not in vim/modal/busy state
3. Use it2 session list to find session IDs

Before Splitting

Check dimensions to plan layout:

it2 session get-info --format=json | jq .grid_size

Common Patterns

Dev Layout (main + logs + server)

MAIN=$ITERM_SESSION_ID
LOGS=$(it2 session split --horizontal -q)
SERVER=$(it2 session split --vertical -q)
it2 session send-text "$LOGS" "tail -f *.log"
it2 session send-text "$SERVER" "npm start"

Send to Another Claude Session

it2 session send-text "$TARGET_SID" "your message"

Monitor a Session

while true; do it2 session get-screen "$SID"; sleep 5; done

When Things Fail

• Session not found: Re-run it2 session list - sessions close, IDs change
• Send-text not delivered: Session is at modal/vim/busy - check screen first
• Split fails: Terminal too small - check grid_size, need ~80x24 minimum per pane