Skip to main content
Generaltmc

session-orchestration

Use when managing multiple iTerm2 sessions, creating split layouts, navigating session hierarchies, or orchestrating terminal workflows across panes.

Stars
32
Source
tmc/it2
Updated
2026-03-25
Slug
tmc--it2--session-orchestration
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/tmc/it2/HEAD/plugins/it2-skills/skills/session-orchestration/SKILL.md -o .claude/skills/session-orchestration.md

Drops the SKILL.md into .claude/skills/session-orchestration.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Session Orchestration

Guidance for managing iTerm2 sessions using the it2 CLI tool.

When to Use

  • Creating multi-pane terminal layouts for development workflows
  • Managing multiple concurrent terminal sessions
  • Navigating and organizing sessions across windows and tabs
  • Sending commands to specific sessions programmatically
  • Setting up reproducible terminal environments

When NOT to Use

  • For simple single-session terminal operations (just use the terminal directly)
  • When iTerm2 is not the active terminal emulator
  • For remote server management (use SSH directly, then optionally it2 for local orchestration)

Quick Start

# List all sessions
it2 session list

# Get current session ID
it2 session current

# Create a horizontal split (new pane below)
it2 session split --horizontal -q

# Create a vertical split (new pane to the right)
it2 session split --vertical -q

# Send text to a session
it2 session send-text "$SESSION_ID" "echo hello"

Core Concepts

Session Identification

Sessions are identified by UUIDs (e.g., A81F7ED5-3F4B-4504-8F14-6C98F9422F72). Use the first 8 characters as shorthand for display purposes.

# Get current session
CURRENT_SID=$ITERM_SESSION_ID

# List sessions with JSON output for parsing
it2 session list --format json

Session Hierarchy

Sessions exist within a hierarchy: Window → Tab → Session (Pane)

# Look up parent tab
it2 session lookup tab "$SID"

# Look up parent window
it2 session lookup window "$SID"

# Find sibling sessions (same split root)
it2 session lookup siblings "$SID"

Split Operations

The -q flag returns only the new session ID (quiet mode), essential for scripting.

# Create split and capture new session ID
NEW_SID=$(it2 session split --horizontal -q)

# Send command to new session
it2 session send-text "$NEW_SID" "cd /path/to/project && npm start"

Layout Patterns

Development Layout (3 panes)

# Start from main session
MAIN=$ITERM_SESSION_ID

# Create editor pane (right)
EDITOR=$(it2 session split --vertical -q)

# Create log pane (bottom of main)
LOGS=$(it2 session split --horizontal -q)

# Set up each pane
it2 session send-text "$EDITOR" "vim ."
it2 session send-text "$LOGS" "tail -f logs/*.log"

Badge Sessions for Identification

Always include the session ID prefix in badges for automation:

it2 session set-badge "$SID" "$(echo $SID | cut -c1-8)\nServer"

Session State Inspection

# Get comprehensive session info
it2 session get-info "$SID" --format json

# Check if session has shell integration
it2 session has-shell-integration "$SID"

# Get current screen contents
it2 session get-screen "$SID"

# Get scrollback buffer (last 100 lines)
it2 session get-buffer "$SID" --lines 100

Best Practices

  1. Always use -q flag when capturing session IDs from split operations
  2. Check session dimensions before splitting: it2 session get-info --format json | jq .grid_size
  3. Use badges to label sessions for visual identification
  4. Verify target session state before sending commands: check screen contents first
  5. Chain commands with && or ; when sending multiple commands

Advanced Usage

See references/hierarchy.md for session hierarchy navigation. See references/layouts.md for complex layout recipes. See workflows/multi-project.md for multi-project setups.