iTerm2 Driver Skill

This skill enables you to fully control the iTerm2 terminal emulator using its Python API. You can create windows, tabs, and splits, inject commands, read screen content, and interact with running applications (CLI/TUI/REPL).

CRITICAL: Script Format

Every Python script MUST use uv with inline metadata:

# /// script
# requires-python = ">=3.14"
# dependencies = [
#   "iterm2",
#   "pyobjc",
# ]
# ///

For screenshots, add "pyobjc-framework-Quartz" to dependencies.

Execution: uv run script_name.py

CRITICAL: Docstring Planning

Every script MUST begin with a comprehensive docstring covering: Tests, Verification Strategy, Screenshots, Key Bindings, and Usage. See examples/00-comprehensive-template.py for the canonical format.

Core Concepts

• Connection: iterm2.run_until_complete(main) for standalone scripts
• Hierarchy: App -> Window -> Tab -> Session
• Key Methods:
  • session.async_send_text("command\n"): Send input
  • session.async_get_screen_contents(): Read screen
  • session.async_split_pane(vertical=True/False): Create splits
  • session.async_close(): Close session

Quick Reference

CRITICAL: Multi-Level Cleanup

Always use try-except-finally with multi-level cleanup:

try:
    # Test logic
except Exception as e:
    print(f"ERROR: {e}")
    raise
finally:
    await session.async_send_text("\x03")  # Ctrl+C
    await asyncio.sleep(0.2)
    await session.async_send_text("q")     # TUI quit
    await asyncio.sleep(0.2)
    await session.async_send_text("exit\n")
    await asyncio.sleep(0.2)
    await session.async_close()

CRITICAL: TUI Layout Verification

TUI elements (borders, modals, status bars) frequently misalign. Always verify layout integrity.

Common issues:

• Box corners not connected to edges (╭ not followed by ─)
• Help modals cut off at screen edges
• Status bars with gaps or truncated content

Quick check pattern:

BOX_CORNERS = '┌┐└┘╭╮╰╯╔╗╚╝'
BOX_HORIZONTAL = '─═━'

# Check corner connectivity
for j, char in enumerate(line):
    if char in '┌╭╔' and j + 1 < len(line) and line[j+1] not in BOX_HORIZONTAL:
        print(f"LAYOUT ERROR: Corner not connected at col {j}")

See references/verification-patterns.md for complete layout verification helpers.

Screenshot Capture (Quartz)

Use pyobjc-framework-Quartz for window-targeted screenshots (not full screen). The pattern uses CGWindowListCopyWindowInfo to find the iTerm2 window ID, then screencapture -l <id>. See examples/00-comprehensive-template.py or references/templates.md for complete implementation.

Test Reporting

Track results with a results dict containing passed, failed, and tests list. Use log_result(name, status, details) for each test and print_summary() to show final counts and return exit code. See references/reporting.md for complete patterns including JSON/JUnit export.

Special Keys Reference

Guidelines

1. Always use uv run – never suggest running python directly
2. Check window exists – if window is not None: before operations
3. Use \r for Enter in TUIs – safer than \n for prompts
4. Dump screen on failure – always show what went wrong
5. Track resources – close all created sessions in finally block
6. Verify layout – check box-drawing characters connect properly

Script Storage

Use descriptive names: watch_build_logs.py, drive_k9s_debug.py

Examples & References

Examples (examples/ directory):

• 00-comprehensive-template.py – Complete template with all patterns
• 01-basic-tab.py – Simple tab creation
• 02-dev-layout.py – Multi-pane layout
• 03-repl-driver.py – REPL automation with verification
• 04-nano-automation.py – TUI editor with cleanup
• 05-screen-monitor.py – ScreenStreamer for real-time monitoring
• 06-environment-vars.py – Environment variable handling
• 07-cleanup-sessions.py – Session cleanup patterns
• 08-badge-control.py – Badge and tab control
• 09-special-keys.py – Special key sequences
• 10-session-reuse.py – Session reuse patterns
• 11-layout-verification.py – TUI layout alignment checks

References (references/ directory):

• templates.md – Complete copy-paste script templates
• verification-patterns.md – All verification helpers including layout checks
• reporting.md – Test reporting patterns, JSON/JUnit export

Links

• iTerm2 Python API
• iTerm2 Scripting Tutorial
• UV Documentation