automate-terminal 0.1.0

Automate opening of new tabs and windows in terminal programs

automate-terminal

Automate opening of new tabs and windows in terminal programs. Currently supports iTerm2, Terminal.app, and Ghostty on macOS, with additional terminals and OSes added by request.

automate-terminal is a best-effort project. Some terminals do not support automation at all!

Installation

pip install automate-terminal

mise install pip:automate-terminal

Or install from source:

git clone https://github.com/yourusername/automate-terminal.git
cd automate-terminal
pip install -e .

Supported Terminals

Terminal	New Tabs/Windows	Switch by ID	Switch by Working Dir	List Sessions	Paste Commands
iTerm2	✅	✅	✅	✅	✅
Terminal.app	✅	❌	✅	✅	✅
Ghostty	✅	❌	❌	❌	✅

Other terminals are not supported; automate-terminal will exit with an error code in other terminals.

Quick Start

# Check if your terminal is supported
automate-terminal check

# Create a new tab
automate-terminal new-tab /path/to/project

# Switch to existing session by directory
automate-terminal switch-to --working-directory=/path/to/project

# Create new window with initialization script
automate-terminal new-window /path/to/project \
  --paste-and-run="source .env && npm run dev"

Commands

check

Detect terminal capabilities.

automate-terminal check
automate-terminal check --output=json

switch-to

Switch to existing session. Errors if not found.

# By working directory (or use --wd alias)
automate-terminal switch-to --working-directory=/path/to/dir

# By session ID (or use --id alias)
automate-terminal switch-to --session-id=w0t0p2:ABC123

# Both (session ID takes precedence)
automate-terminal switch-to \
  --session-id=w0t0p2:ABC123 \
  --working-directory=/path/to/dir

# Match sessions in subdirectories
automate-terminal switch-to --working-directory=/path/to/dir --subdirectory-ok

new-tab

Create new tab.

automate-terminal new-tab /path/to/dir

new-window

Create new window.

automate-terminal new-window /path/to/dir

list-sessions

List all sessions.

automate-terminal list-sessions
automate-terminal list-sessions --output=json

Options

Output Format

• --output=text - Human-readable (default)
• --output=json - JSON for programmatic use
• --output=none - Silent

Paste and Run

Execute commands after creating/switching sessions.

--paste-and-run="echo 'I run unconditionally'"
--paste-and-run-bash="echo 'I only run if the current shell is bash'"
--paste-and-run-zsh="echo 'I only run if the current shell is zsh'"
--paste-and-run-fish="echo 'I only run if the current shell is fish'"

Shell-specific flags override generic --paste-and-run when detected shell matches.

Debug and Dry Run

--debug     # Enable debug logging to stderr
--dry-run   # Log actions instead of executing them

Use --dry-run to see what AppleScript commands would be executed without actually running them. Useful for debugging and understanding what the tool will do.