it2
Programmatic control of iTerm2 — sessions, splits, text I/O, buffer reading,
state detection, and real-time events over the Unix socket API.
it2 turns iTerm2 into an orchestration layer for terminal workflows. Split
panes, send commands, read output, detect state — from shell scripts, CI
pipelines, or AI agents like Claude Code and Gemini CLI.
Install
Requires Go 1.21+ and iTerm2 3.3.0+.
go install github.com/tmc/it2/cmd/it2@latest
it2 auth check # iTerm2 will prompt to allow API access
Quick Start
it2 session list # list all sessions
it2 session split -q # split pane, print new session ID
it2 session send-text $SID "make test" # send text to a session
it2 session get-screen $SID # read visible screen content
it2 session get-buffer $SID --lines 100 # read scrollback buffer
Agent Integration
it2 detects and interacts with AI agents running in terminal sessions.
Built-in support for Claude Code; extensible to any agent via plugins.
State Detection
Check what a session is doing without reading the full buffer:
it2 session is-active $SID # exit 0 if agent is working
it2 session has-modal $SID # exit 0 if modal dialog detected
it2 session suggest-action $SID # recommend: continue, approve, wait
it2 session claude-status $SID # human-readable Claude Code status
it2 session get-state $SID --agent=auto # full state as structured output
Auto-Respond
Watch a session and automatically respond to prompts:
it2 session autorespond $SID # default patterns
it2 session autorespond $SID --pattern "Continue?" # custom pattern
The embedded claude-auto-approve plugin checks safety heuristics before
approving any modal. See Claude Plugins Reference
for hook setup and event logging.
Multi-Agent Workflows
it2 supports multi-agent patterns where sessions split, communicate, and
read each other's output.
Split and Delegate
# Create a worker session and send it a task
WORKER=$(it2 session split -q --vertical)
it2 session set-badge "$WORKER" "$(echo $WORKER | cut -c1-8)\nWorker"
it2 session send-text "$WORKER" "cd /project && make lint"
Cross-Session Communication
# Read a session's output
it2 session get-buffer "$WORKER" --lines 50
# Wait for prompt, then send next command
it2 session send-text --require is-at-prompt "$WORKER" "make test"
# Skip delivery confirmation for speed
it2 session send-text --skip-confirm "$WORKER" "echo done"
Prime Protocol
Output inter-session communication guidelines for an agent:
it2 prime | it2 session send-text $SID -f -
This sends a protocol document that teaches agents how to respond via
it2 session send-text, include session IDs, and format messages.
Broadcast
Send the same input to multiple sessions simultaneously:
it2 broadcast set $SID1 $SID2 $SID3 # create broadcast domain
it2 broadcast send "git pull" # send to all sessions in domain
it2 broadcast clear # tear down broadcast domain
Plugin System
Plugins are executables on your PATH matching it2-session-*, it2-tab-*,
or it2-window-*. They receive session context as JSON on stdin and return
enrichment data on stdout.
it2 plugin list # show discovered plugins with source and hash
it2 plugin run <name> # run a plugin directly
Embedded plugins:
| Plugin | Type | Purpose |
|---|
is-at-prompt | session | Detect shell prompt (exit 0 = at prompt) |
claude-has-modal | session | Detect Claude Code modal dialogs |
claude-suggest-action | session | Recommend intervention for stuck sessions |
claude-auto-approve | session | Auto-approve safe operations |
claude-is-safe-operation | session | Check if an operation is safe to auto-approve |
has-no-queued-claude-messages | session | Check for pending message queue |
is-claude.sh | session-process | Detect if session runs Claude Code |
tree.sh | session-process | Show process hierarchy for a session |
PATH plugins shadow embedded plugins of the same name.
See docs/TAXONOMY.md for the full plugin model.
Configuration
Environment Variables