iterm2-automation

iTerm2 Automation & Scripting

Help the user automate iTerm2 with triggers, Python API scripts, and escape codes.

User's Environment

• iTerm2 3.6.8 on macOS, using zsh
• Python scripts directory: ~/Library/Application Support/iTerm2/Scripts/
• No existing Python scripts

Triggers

Triggers are regex-based rules that fire actions when matching text appears in terminal output. They're the simplest form of automation — no coding required.

Configuration Path

Settings > Profiles > Advanced > Triggers > Edit

Each trigger has:

• Regex — ICU regular expression (matched line-by-line)
• Action — What to do when matched
• Parameter — Action-specific value
• Instant — Fire immediately without waiting for newline (useful for password prompts)

Common Trigger Patterns

Highlight errors in red:

• Regex: (?i)\b(error|fail|fatal|exception)\b
• Action: Highlight Text
• Parameter: Red text color

Notification on build completion:

• Regex: (BUILD SUCCESSFUL|Build complete|✓ Done)
• Action: Post Notification
• Parameter: "Build finished"

Auto-fill sudo password prompt:

• Regex: ^\[sudo\] password
• Action: Open Password Manager
• Instant: checked

Mark deployment events:

• Regex: Deployed to (production|staging)
• Action: Set Mark + Post Notification

Highlight IP addresses:

• Regex: \b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b
• Action: Make Hyperlink

For the full list of all 26 trigger actions, read references/trigger-actions.md.

Trigger Tips

• Triggers process the last 3 wrapped lines by default (adjustable in Advanced Settings)
• Use capture groups \1, \2 in parameters to reference matched text
• "Stop Processing Triggers" action prevents subsequent triggers from firing — useful for priority ordering
• Triggers are profile-specific; use dynamic profiles to share triggers across contexts

Python API

iTerm2's Python API enables deeper automation than triggers. Scripts can create windows, monitor sessions, build custom status bar components, and respond to events.