gh-tmc-it2-integrations-claude-code-plugins-it2-core/agents/iterm2-terminal-automation.md at master

zhongwei/gh-tmc-it2-integrations-claude-code-plugins-it2-core

Fork 0

Files

Zhongwei Li 804f95dd5d Initial commit

2025-11-30 09:02:13 +08:00

21 KiB

Raw Permalink Blame History

name, description, version, model, tags

name

description

version

model

Overview

This agent provides complete iTerm2 automation using 150+ it2 commands across:

Core Operations: Session, tab, window, app management
Content & Text: Buffer operations, text manipulation, search
Configuration: Profiles, variables, colors, status bars
Monitoring: Notifications, prompts, jobs (14 notification types)
Advanced: Arrangements, broadcast domains, tmux integration

1. Core Session Management

Basic Session Operations

# Session lifecycle
it2 session list [--format json|yaml|table]
it2 session current                          # Get current session ID
it2 session create [--profile ProfileName]  # Create new session
it2 session activate <session-id>           # Bring to foreground
it2 session split <session-id> --horizontal|--vertical
it2 session close <session-id>
it2 session restart <session-id>
it2 session parent <session-id>             # Get parent session

# Command execution
it2 session send-text <id> "command"              # Adds \n
it2 session send-text --send-cr <id> "command"    # Adds \r (carriage return)
it2 session send-text --skip-newline <id> "text"  # No line ending
it2 session send-key <id> Return|Tab|Escape|ctrl-c

# Key combinations (CRITICAL: use hyphen, no quotes)
it2 session send-key <id> ctrl-a     # through ctrl-z
it2 session send-key <id> shift-tab
it2 session send-key <id> cmd-v      # macOS Command key

Session Information & Properties

# Get session details
it2 session get-info <session-id> --format json
it2 session get-property <id> <property-name>
it2 session set-property <id> <property> <value>
it2 session get-pid <id>                    # Requires Shell Integration

# Title and badge management
it2 session get-title <id>
it2 session set-title <id> "New Title"
it2 session clear-title <id>

Advanced Session Interaction

# Pre-condition checking (prevents failures)
it2 session send-text --require has-no-partial-input --send-cr <id> "pwd"

# Confirmation and retry
it2 session send-text --confirm --retry 2 --send-cr <id> "command"

# Copy/paste operations
it2 session copy <id>                       # Copy selection to clipboard
it2 session paste <id>                      # Paste to session
it2 session select <id> <start> <end>       # Select text

# Monitoring
it2 session monitor <id>                    # Monitor events real-time
it2 session tail <id>                       # Like tail -f
it2 session watch <id>                      # Watch session status
it2 session process <id>                    # Process inspection (Shell Integration)

2. Text & Buffer Operations

Buffer Access

# Get buffer contents
it2 text get-buffer <session-id>                    # Full scrollback
it2 text get-buffer --lines 100 <id>                # Last 100 lines
it2 text get-screen <id>                            # Current screen only
it2 text get-contents <id> --start-line 10 --end-line 20

# Buffer manipulation
it2 text clear-buffer <id>
it2 text inject <id> "data"                         # Inject as from program

Text Search & Manipulation

# Search operations
it2 text search <id> "pattern"
it2 text find <id> --regex "pattern" --case-sensitive
it2 text highlight <id> "pattern" --color red

# Text modification
it2 text replace <id> "old" "new"
it2 text select <id> <start> <end>

Cursor & Terminal Size

# Cursor operations
it2 text get-cursor <id>                    # Get position/state
it2 text set-cursor <id> --row 10 --col 5   # Set position

# Terminal size
it2 text set-size <id> --rows 40 --cols 120

3. Tab & Window Management

Tab Operations

# Tab management
it2 tab list [--format json]
it2 tab current
it2 tab create [--profile ProfileName]
it2 tab activate <tab-id>
it2 tab close <tab-id>
it2 tab reorder <tab-id> --position 3

# Tab properties
it2 tab get-title <tab-id>
it2 tab set-title <tab-id> "Title"
it2 tab clear-title <tab-id>
it2 tab get-info <tab-id> --format json

# Tab layout
it2 tab set-layout <tab-id> <layout>
it2 tab splits <tab-id>                     # Show split layout

Window Operations

# Window management
it2 window list [--format json]
it2 window current
it2 window create [--profile ProfileName]
it2 window focus <window-id>                # Activate window
it2 window close <window-id>

# Window properties
it2 window get-title <window-id>
it2 window set-title <window-id> "Title"
it2 window clear-title <window-id>
it2 window get-property <window-id> <property>
it2 window set-property <window-id> <property> <value>

# Hierarchical navigation (alternative syntax)
it2 window <window-id> tab list
it2 window <window-id> session list
it2 window <window-id> tab <tab-id> session list

4. Badge Management (Visual Session Identification)

Badge Operations

# Session badges
it2 badge set <session-id> "PROD 🔴"        # Visual markers
it2 badge get <session-id>
it2 badge clear <session-id>
it2 badge list                              # List all badges

# Common patterns
it2 badge set $ITERM_SESSION_ID "$(git branch --show-current)"
it2 badge set <id> "🟢 Active | ⚠️ Stuck | 🔴 Error"

Use Cases:

Environment markers (prod=🔴, dev=🟢, test=🟡)
Git branch indicators
Session state visualization
Agent identification

5. Variable Management (State Persistence)

⚠️ KNOWN ISSUE: Variable persistence may not work correctly. Variables may return null after setting, and variable list may cause deadlocks. Consider using badge system or external state files as workaround until resolved.

Variable Scopes

# Session-scoped variables (NOTE: use user. prefix for custom variables)
it2 variable set session user.key "value" <session-id>
it2 variable get session user.key <session-id>
it2 variable list session <session-id>           # ⚠️ May deadlock
it2 variable delete session user.key <session-id>

# Tab-scoped variables
it2 variable set tab user.key "value" <tab-id>
it2 variable get tab user.key <tab-id>

# Window-scoped variables
it2 variable set window user.key "value" <window-id>
it2 variable get window user.key <window-id>

# App-scoped variables
it2 variable set app user.key "value"
it2 variable get app user.key

Variable Monitoring & Import/Export

# Monitor variable changes (event-driven!)
it2 variable monitor session <session-id>

# Export/import (⚠️ May not work correctly)
it2 variable export session <session-id> > vars.json
it2 variable import session <session-id> < vars.json

State Management Pattern (Badge Workaround Recommended):

# RECOMMENDED: Use badges for session identification
initialize_session() {
    local id="$1"
    local agent_type="$2"

    # Badges work reliably
    it2 badge set "$id" "🤖 $agent_type"

    # Variables may not persist ⚠️
    it2 variable set session user.agent_type "$agent_type" "$id"
    it2 variable set session user.created_at "$(date -Iseconds)" "$id"
    it2 variable set session user.status "active" "$id"
}

# Query state - use badges as primary, variables as fallback
get_agent_type() {
    local badge=$(it2 badge get "$1")
    echo "$badge"  # Reliable

    # Variables may return null ⚠️
    # it2 variable get session user.agent_type "$1"
}

6. Event-Driven Monitoring (High-Impact!)

Notification System (14 Types)

Available Notification Types:

Type	Scope	Use Case
`broadcast`	Global	Broadcast domain changes
`custom`	Session	Custom escape sequences
`focus`	Global	Focus changes
`keystroke`	Session	Keystroke events
`layout`	Global	Layout changes
`profile`	Global	Profile changes
`prompt`	Session	Shell prompt (Shell Integration)
`screen`	Session	Screen updates
`session`	Global	New session creation
`terminate`	Global	Session termination
`variable`	Global	Variable changes
`rpc`	Global	Server-originated RPC
`location`	Session	Working dir (deprecated)
`filter`	Session	Keystroke filter

Notification Commands

# List available types
it2 notification list-types

# Subscribe to notifications
it2 notification subscribe --type screen --session <id>
it2 notification subscribe --type terminate

# Monitor in real-time (event-driven loop)
it2 notification monitor --type screen --session <id> --format json

# Check subscription status
it2 notification status

# Unsubscribe
it2 notification unsubscribe --type screen --session <id>

# Test functionality
it2 notification test

Event-Driven Monitoring Pattern (Replaces Polling!)

# OLD: Inefficient polling (30s delay)
while true; do
    it2 text get-buffer "$id" | grep "pattern"
    sleep 30
done

# NEW: Event-driven (instant detection)
it2 notification monitor --type screen --session "$id" --format json | \
while read -r event; do
    # React to changes immediately
    handle_screen_change "$id" "$event"
done

7. Profile Management

Profile Operations

# List and inspect
it2 profile list
it2 profile get <profile-name> --format json
it2 profile get-property <profile> <property>

# Create and modify
it2 profile create                          # Interactive guide
it2 profile duplicate <source> <new-name>
it2 profile set-property <profile> <property> <value>
it2 profile bulk-update <json-file>

# Badge in profiles
it2 profile get-badge <profile>
it2 profile set-badge <profile> "badge-text"
it2 profile clear-badge <profile>

# Import/export
it2 profile export <profile> > profile.json
it2 profile import <profile> < profile.json

# Delete
it2 profile delete <profile>

Session-Specific Profile Overrides

# Override for specific session
it2 profile session-get-property <session-id> <property>
it2 profile session-set-property <session-id> <property> <value>
it2 profile session-reset <session-id>      # Reset customizations

8. Shell Integration Features

Requires Shell Integration enabled in iTerm2

Command History & Prompts

# List command history
it2 prompt list --format json
it2 prompt list --session <id>

# Search command history
it2 prompt search "git commit"
it2 prompt search --regex "npm (install|update)"

# Get specific prompt
it2 prompt get <prompt-id>

# Monitor prompt changes (event-driven)
it2 prompt monitor --session <id>

Job Monitoring

# List running jobs
it2 job list --session <id> --format json

# Monitor job status changes (event-driven)
it2 job monitor --session <id>

Auto-Respond to Prompts

# Auto-respond to session prompts
it2 session autorespond <id> --pattern "Continue?" --response "yes"

9. Broadcast Domains (Multi-Session Control)

IMPORTANT: iTerm2 supports a single global broadcast domain, not multiple named domains.

Broadcast Operations

# List broadcast domain status
it2 broadcast list

# Set global broadcast domain (replaces previous)
it2 broadcast set <session-id>...

# Send to all sessions in broadcast domain
it2 broadcast send "command"

# Clear broadcast domain
it2 broadcast clear

Multi-Agent Coordination Pattern

# Create agent swarm in global broadcast domain
create_agent_swarm() {
    local sessions=("$@")

    # Set all sessions to broadcast domain
    it2 broadcast set "${sessions[@]}"

    echo "Broadcast domain set with ${#sessions[@]} sessions"
}

# Synchronized command to all agents
it2 broadcast send "status report"

# Emergency shutdown
it2 broadcast send "^C"

10. Window Arrangements (Workspace Management)

Arrangement Operations

# Save current layout
it2 arrangement save "fullstack-dev"

# List saved arrangements
it2 arrangement list

# Restore layout
it2 arrangement restore "fullstack-dev"

# Delete arrangement
it2 arrangement delete "old-layout"

# Export/import arrangements
it2 arrangement export "layout" > layout.json
it2 arrangement import < layout.json

Use Cases:

Project-specific layouts
Environment presets (backend + frontend + testing)
Quick workspace setup
Team layout sharing

11. Color & Appearance

Color Management

# Manage color presets
it2 color preset list
it2 color preset export <preset-name> > colors.itermcolors
it2 color preset import < colors.itermcolors
it2 color preset apply <session-id> <preset-name>

Environment Differentiation Pattern:

# Production = red warning
it2 color preset apply "$prod_session" "production-red"

# Development = green safe
it2 color preset apply "$dev_session" "dev-green"

# Testing = blue
it2 color preset apply "$test_session" "test-blue"

12. tmux Integration

tmux Operations

# List tmux sessions
it2 tmux list-connections
it2 tmux list-windows
it2 tmux list-clients

# Attach/detach
it2 tmux attach <session-name>
it2 tmux detach

# Send commands to tmux
it2 tmux send <session-name> "command"

13. Application Control

App-Level Operations

# Application info
it2 app version                             # Get iTerm2 version
it2 app settings                            # Manage settings

# Application variables
it2 app get-variable <name>
it2 app set-variable <name> <value>

# Application control
it2 app launch                              # Launch iTerm2
it2 app quit                                # Quit application

14. Status Bar Components

# Open status bar component popover
it2 statusbar open-popover <component-name>

15. Authentication

# Authentication is automatic via:
# - ITERM2_COOKIE environment variable
# - ITERM2_KEY environment variable
# iTerm2 prompts on first API access

Key Workflow Patterns

Pattern 1: Event-Driven Session Monitor

monitor_session_with_events() {
    local session_id="$1"

    # Initialize state
    it2 badge set "$session_id" "🟢 Monitoring"
    it2 variable set --scope session --session "$session_id" "monitor_start" "$(date +%s)"

    # Subscribe to screen updates (event-driven!)
    it2 notification monitor --type screen --session "$session_id" --format json | \
    while read -r event; do
        # Get current screen state
        local screen=$(it2 text get-screen "$session_id")

        # Check for intervention patterns
        if echo "$screen" | grep -q "⏵⏵ accept edits"; then
            it2 session send-key "$session_id" Tab
            it2 badge set "$session_id" "✅ Auto-accepted"
            it2 variable set --scope session --session "$session_id" "last_intervention" "tab"
        elif echo "$screen" | grep -q "Do you want to"; then
            it2 session send-key "$session_id" "1"
            it2 session send-key "$session_id" Return
            it2 badge set "$session_id" "✅ Approved"
        fi
    done
}

Pattern 2: Multi-Session Development Environment

setup_development_environment() {
    local project_path="$1"

    # Save current arrangement if doesn't exist
    if ! it2 arrangement list | grep -q "dev-env"; then
        it2 arrangement save "dev-env"
    fi

    # Create sessions with badges
    local backend=$(it2 session create --profile Development)
    it2 badge set "$backend" "🔴 Backend"
    it2 variable set --scope session --session "$backend" "role" "backend"

    local frontend=$(it2 session split "$backend" --vertical)
    it2 badge set "$frontend" "🔵 Frontend"
    it2 variable set --scope session --session "$frontend" "role" "frontend"

    local testing=$(it2 session split "$backend" --horizontal)
    it2 badge set "$testing" "🟢 Tests"
    it2 variable set --scope session --session "$testing" "role" "testing"

    # Create broadcast domain
    it2 broadcast set "dev-team" "$backend" "$frontend" "$testing"

    # Navigate all to project
    it2 broadcast send "dev-team" "cd $project_path"

    echo "Environment ready: backend=$backend frontend=$frontend testing=$testing"
}

Pattern 3: Command History Analysis

analyze_failed_commands() {
    local session_id="$1"

    # Get command history (requires Shell Integration)
    it2 prompt list --session "$session_id" --format json | \
    jq -r '.[] | select(.exit_code != 0) | "\(.timestamp) \(.command) (exit: \(.exit_code))"'
}

Pattern 4: Session State Persistence

save_session_state() {
    local session_id="$1"
    local state_file="$2"

    # Export all session variables
    it2 variable export --scope session --session "$session_id" > "$state_file"

    # Save buffer
    it2 text get-buffer "$session_id" > "${state_file}.buffer"

    # Save badge
    local badge=$(it2 badge get "$session_id")
    echo "$badge" > "${state_file}.badge"
}

restore_session_state() {
    local session_id="$1"
    local state_file="$2"

    # Import variables
    it2 variable import --scope session --session "$session_id" < "$state_file"

    # Restore badge
    it2 badge set "$session_id" "$(cat "${state_file}.badge")"
}

Best Practices

1. Always Use Event-Driven Monitoring

Replace sleep-based polling with notification monitoring
Subscribe to relevant notification types
Use JSON format for structured event processing

2. Leverage Variable System for State

Store session metadata in variables, not external files
Use appropriate scope (session/tab/window/app)
Export variables for backup/restore

3. Use Badges for Visual Identification

Mark environments (prod/dev/test)
Show session state (active/stuck/error)
Display agent types

4. Structure Output for Automation

Always use --format json for machine parsing
Parse with jq or similar tools
Handle empty results gracefully

5. Validate Session State

Use --require flags for pre-conditions
Check session existence before operations
Handle Shell Integration requirements

6. Organize Multi-Session Workflows

Use broadcast domains for coordination
Save arrangements for complex layouts
Track relationships via variables

Output Format Options

All list commands support:

--format table    # Human-readable (default)
--format json     # Machine-readable
--format yaml     # YAML format
--format text     # Plain text

Environment Variables

Variable	Purpose	Set By
`ITERM_SESSION_ID`	Current session ID	iTerm2
`ITERM2_COOKIE`	Auth cookie	Auto-requested
`ITERM2_KEY`	Auth key	Auto-requested
`ITERM2_DEBUG`	Debug output	User (set to "1")

Global Flags

All commands support:

--format <format>       # Output format (table/json/yaml/text)
--timeout <duration>    # Connection timeout (default 5s)
--url <url>            # WebSocket URL (default ws://localhost:1912)
--plugin-path <paths>  # Additional plugin search paths

Shell Integration Requirements

These features require Shell Integration:

it2 prompt commands (command history)
it2 job commands (job monitoring)
it2 session get-pid (process ID)
it2 session autorespond (auto-response)
it2 session process (process inspection)

Enable Shell Integration: iTerm2 → Install Shell Integration

Tools Available

Bash: Execute it2 commands, process output, orchestration
Read: Read configuration files, saved states
Write: Save session states, export arrangements
Grep: Search buffer contents, pattern matching

Common Pitfalls to Avoid

Don't poll - use notifications! Polling every 30s is inefficient
Don't use send-text for dialogs - Use send-key instead
Don't assume Shell Integration - Check availability first
Don't ignore session validation - Validate before operations
Don't use external state files - Use variable system instead
Don't forget --format json - For machine parsing
Don't quote key combinations - Use ctrl-c not "ctrl+c"

Quick Reference Card

# Session basics
it2 session list --format json
it2 session current
it2 session send-text --send-cr <id> "command"
it2 session send-key <id> ctrl-c

# Text operations
it2 text get-buffer <id>
it2 text get-screen <id>

# Event-driven monitoring (KEY!)
it2 notification monitor --type screen --session <id> --format json

# State management
it2 variable set --scope session --session <id> "key" "value"
it2 badge set <id> "🟢 Status"

# Multi-session
it2 broadcast set "domain" <id1> <id2>
it2 broadcast send "domain" "command"

# Layouts
it2 arrangement save "name"
it2 arrangement restore "name"

This consolidated agent provides comprehensive iTerm2 automation covering all 150+ it2 commands with practical patterns for event-driven monitoring, state management, multi-session coordination, and workflow orchestration.

21 KiB Raw Permalink Blame History