iterm-multi-tasking

name	iterm-multi-tasking
description	Create iTerm2 multi-pane grids for running parallel agents (gemini, claude, codex, etc.) via Python/AppleScript automation. This skill should be used when the user asks to create iTerm2 pane layouts, run multiple CLI agents in parallel, automate terminal workflows, or send commands to multiple panes. Covers critical gotchas like properly triggering Enter for interactive programs.

iTerm2 Multi-Tasking Skill

Create and control iTerm2 multi-pane grids for running parallel CLI agents via Python and AppleScript.

When to Use This Skill

• Creating iTerm2 windows with multiple panes (grids)
• Running parallel CLI agents (gemini, claude, codex, etc.) in separate panes
• Automating terminal workflows with multiple concurrent processes
• Sending commands or prompts to interactive programs in panes

Core Concepts

Architecture

Python Script
    └── subprocess.run(["osascript", "-e", applescript])
            └── AppleScript controls iTerm2
                    └── iTerm2 sessions (panes)

iTerm2 AppleScript Hierarchy

iTerm2 Application
└── Window
    └── Tab
        └── Sessions (panes)
            - session 1, session 2, ... session N

Critical Gotchas

1. Sending Enter to Interactive Programs (MOST IMPORTANT)

Problem: Default write text does NOT reliably trigger Enter for interactive CLI programs like gemini --yolo, claude, etc.

What FAILS:

-- This does NOT work for interactive programs
write text "your prompt here"

What WORKS:

-- Explicitly append return character
write text "your prompt here" & return

Why: The default write text newline is handled at iTerm2's level, but interactive CLI programs may not receive it as a proper Enter keystroke. Appending & return makes the return character part of the text payload itself.

2. Pane Numbering After Splits

When splitting panes, session numbers are assigned in creation order, NOT visual order. After creating a 4x3 grid:

Split Strategy:
1. Start with 1 pane
2. Split horizontally 3 times → 4 columns (sessions 1-4)
3. Split each column vertically 2 times → 3 rows per column

Session numbers in a 4x3 grid:
+-----+-----+-----+------+
|  1  |  4  |  7  |  10  |
+-----+-----+-----+------+
|  2  |  5  |  8  |  11  |
+-----+-----+-----+------+
|  3  |  6  |  9  |  12  |
+-----+-----+-----+------+

3. Timing and Delays

• Add small delays (0.2-0.3s) between sending commands to different panes
• Wait for interactive programs to fully start before sending prompts (5+ seconds for gemini/claude)
• Without delays, commands may be dropped or sent to wrong panes

4. Referencing Sessions After Splits

After splitting, reference sessions within the tab context:

tell newWindow
    tell current tab
        tell session 1
            write text "command" & return
        end tell
    end tell
end tell

Code Templates

Basic Pattern: Run AppleScript from Python

import subprocess

def run_applescript(script: str) -> str:
    """Execute AppleScript and return output."""
    result = subprocess.run(
        ["osascript", "-e", script],
        capture_output=True,
        text=True
    )
    if result.returncode != 0:
        raise RuntimeError(f"AppleScript error: {result.stderr}")
    return result.stdout.strip()

Creating a Grid Layout

tell application "iTerm2"
    activate
    set newWindow to (create window with default profile)

    tell current session of newWindow
        -- Create columns (horizontal splits)
        split horizontally with default profile
        split horizontally with default profile
        -- Now have 3 columns
    end tell

    tell newWindow
        tell current tab
            -- Split each column into rows (vertical splits)
            tell session 1
                split vertically with default profile
            end tell
            tell session 3
                split vertically with default profile
            end tell
            tell session 5
                split vertically with default profile
            end tell
            -- Now have 3x2 = 6 panes
        end tell
    end tell
end tell

Sending Commands to Interactive Programs

tell newWindow
    tell current tab
        -- Start interactive program
        tell session 1
            write text "cd ~/project && gemini --yolo"
        end tell

        delay 5  -- Wait for program to start

        -- Send prompt with explicit return
        tell session 1
            write text "your prompt here" & return
        end tell
    end tell
end tell

Example Script

A complete working example is available at scripts/iterm_12_panes.py. This script:

1. Creates a new iTerm2 window with 12 panes (4x3 grid)
2. Runs gemini --yolo in 9 panes
3. Sends unique prompts to each pane for parallel processing

To use as a template, read scripts/iterm_12_panes.py and modify:

• Number of panes and grid dimensions
• The command to run in each pane
• The prompts to send to each pane
• Delays based on how long programs take to start

Common Use Cases

Parallel Agent Execution

Run multiple AI agents simultaneously on different tasks:

• OCR processing across multiple documents
• Code review on multiple files
• Data analysis on multiple datasets

Batch Processing

Send similar commands to multiple panes with varying parameters:

• Same base command, different input files
• Same prompt template, different variables

Debugging Tips

1. Commands not executing: Check if & return is appended for interactive programs
2. Wrong pane receives command: Add delays between commands, verify session numbers
3. AppleScript errors: Run the AppleScript directly in Script Editor to debug
4. Program not ready: Increase delay before sending prompts